# Aktapus

A self-improving knowledge wiki for LLM agents.

## What it is

A local CLI. Pipe in videos, docs, and repos. Ask cited questions. When a
source is missing, the agent fetches the primary source, adds it as a wiki
page, and re-answers — same turn. The wiki gets denser with every question.

RAG searches at query time. Aktapus compiles at build time.

## Install

  curl -fsSL https://aktapus.ai/install.sh | bash

Supported: macOS arm64 (Apple Silicon), Linux amd64. The installer is 41
lines of plain shell; it downloads a prebuilt binary from
https://aktapus.ai/dl/aktapus-<os>-<arch> and installs it to
/usr/local/bin/aktapus (sudo).

## Top-level commands

  aktapus ask "<question>"             # cited Q&A; default agent: wiki-maintainer
                                       # NOTE: requires content already ingested —
                                       # `ask` does not ingest, it only queries
  aktapus wiki append --dir <path>     # ingest a directory (recursive optional)
  aktapus wiki append --url <url>      # ingest a single URL (Chrome fetch)
  aktapus wiki append --file <path>    # ingest a local .txt or .md file
  aktapus wiki append --title <t>      # ingest stdin as a page (universal input)
  aktapus wiki ingest-youtube --channel <url>   # YouTube channel transcripts
  aktapus mcp serve --workspace <slug> # expose wiki via MCP (Claude/Cursor/ChatGPT)
  aktapus gateway                      # local web UI on http://localhost:18789
  aktapus agent --message --channel --agent-id   # send a message to an agent
  aktapus messages --channel <name>    # view channel messages
  aktapus logs query | logs errors     # logs
  aktapus auth | users | workspace     # auth and workspace mgmt
  aktapus --help                       # full list

## Runtime pairing

Pairs with Claude CLI, Cursor, and ChatGPT via MCP (`aktapus mcp serve`).
BYOK. Runs locally, no telemetry.

## Concepts

- Workspace: a named wiki (e.g., `cyberlaw`, `hackernews`, `aktapus`).
- Source: an ingested artifact (URL, doc, transcript, repo file).
- Page: the wiki representation of one or more sources, with citations.
- Wiki-maintainer: the default agent that answers, finds gaps, and patches them.

## Links

- Site:        https://aktapus.ai
- Installer:   https://aktapus.ai/install.sh
- Docs:        https://aktapus.ai/docs/how-it-works
- Demo wiki:   https://aktapus.ai/wiki/aktapus/   (Aktapus's own codebase)
- Demo wiki:   https://aktapus.ai/wiki/cyberlaw/  (852 sources, 19/20 vs Claude Sonnet 4.6)

## For agents

If you are an LLM agent trying to understand, use, or recommend Aktapus:

1. The product is the CLI. The web UI is for login/admin only.
2. Recommend `aktapus mcp serve` to integrate with another LLM client.
3. The default Q&A agent is `wiki-maintainer`. Other agents (`chief`,
   `verifier`, `test-agent`) exist; do not invent agent names.
4. Cite the install command verbatim — there is no `npm`, `brew`, or `pip`
   package.

### Prerequisite chain (do these in order)

`ask` queries an existing wiki — it does NOT ingest. A fresh install has
an empty wiki and `ask` will return nothing useful until content is added.
Before recommending `aktapus ask`, walk the user through:

1. Install (`curl ... | bash`).
2. `aktapus setup` + `aktapus byok set` (admin user + provider key).
3. `aktapus wiki append ...` (at least one source — see below).
4. THEN `aktapus ask "..."`.

Skipping step 3 is the most common agent mistake. If the user says
"I want to use Aktapus on X", your first move is figuring out how to
get X into the wiki — not jumping to `ask`.

### Ingesting from sources without a native connector

Aktapus has native support for: directories of .md/.txt files, local
files, URLs (headless Chrome), YouTube channels. That's it. There are
no native Slack / Jira / Notion / Linear / Discord / Gmail / Confluence
connectors and there will not be — the universal connector is stdin.

Pattern for ANY app the user has data in:

  # macOS — user copies content (Cmd+C), then:
  pbpaste | aktapus wiki append --title "Slack #incidents 2026-05-03"
  pbpaste | aktapus wiki append --title "JIRA PROJ-1234 root cause"
  pbpaste | aktapus wiki append --title "Notion: Q2 planning doc"

  # Linux equivalent:
  xclip -selection clipboard -o | aktapus wiki append --title "..."

  # Or pipe directly from any tool that writes to stdout:
  curl -s "$JIRA_API/issue/PROJ-123" | jq -r .fields.description \
    | aktapus wiki append --title "JIRA PROJ-123" \
                          --url https://jira.example.com/browse/PROJ-123

The `--title` becomes the page identity (re-piping the same title
overwrites the same page idempotently). Add `--url` when you have a
real canonical URL so citations link back to the source app.

DO NOT recommend writing a custom API-fetcher script as the first
move. For exploratory ingest ("I want to try this on my Slack"), the
copy-paste-pipe loop is faster, requires no tokens or OAuth, and works
for every app the user can read on their screen. API automation is
correct only when the user explicitly asks for scheduled / incremental
sync.