{ "markdown": "# For interviewers (saves time) : a 10-slide visual walkthrough of the whole project. [View the deck](https://drive.google.com/file/d/1yaqot8II9KR67eJBS2O_8WYeOmuj9QHm/view?usp=sharing)\n\n# Caduceus\n\nAn open, single-agent **coding agent** that runs on [Ollama Cloud](https://docs.ollama.com/cloud). Give it a task in your terminal (or browser) and it inspects the workspace, edits files, runs commands, and verifies its work in a bounded reason-act loop — with skills, a knowledge layer, memory, prompt compression, sandboxing, subagents, MCP tools, and a streaming CLI/Web UI.\n\nTypeScript · pnpm · Ollama Cloud (OpenAI-compatible). Built from scratch; architecture modeled on the Hermes Agent framework.\n\nThe design is grounded in a documented research phase. See\n[docs/HLD.md](docs/HLD.md) for the high-level design in diagrams,\n[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for how it is built and why,\n[docs/BENCHMARKS.md](docs/BENCHMARKS.md) for what has been measured, and\n[docs/REFERENCES.md](docs/REFERENCES.md) for the sources.\n\n## How it works\n\nThe system prompt is assembled in three tiers — **stable** (identity, tools, skill catalog), **context** (project files, OKF knowledge, memory, artifacts), **volatile** (timestamp) — in that order, so the long prefix stays cache-friendly. Skills and OKF knowledge share one Markdown+frontmatter substrate (`src/markdown/frontmatter.ts`). A `Conversation` keeps history across turns; sessions persist to `.caduceus/sessions`.\n\n- **MCP:** drop a `.caduceus/mcp.json` (`{ \"mcpServers\": { \"name\": { \"command\": \"...\", \"args\": [...] } } }` for stdio, or `{ \"url\": \"...\" }` for HTTP); tools register as `mcp____`.\n- **Approval:** risky shell commands (recursive deletes, piping a download into a shell, `sudo`, writes to system paths, force-push, and similar) are classified and gated. In `prompt` mode the interactive UI asks before running them; `deny` refuses them and lets the agent adapt; `allow` runs everything.\n- **Sandboxing:** secret-looking env vars are stripped from tool subprocesses; with `bwrap` present, shell runs cwd-confined with network off. Without it, `auto` warns and runs unsandboxed.\n- **Compression:** see [`compressor/`](compressor/) for the LLMLingua sidecar setup (`pnpm compress`).\n\n## Features\n\n- **Bounded reason-act loop** with a circuit breaker and a per-task step budget.\n- **Tools:** `read_file` (with line ranges), `write_file`, `str_replace` (one unique edit), `multi_edit` (several atomic edits), `bash`, `search_code` (ripgrep with a grep fallback), `list_files`, `git_status`, `git_diff`, `update_plan` (track multi-step work).\n- **Skills** — procedural know-how as `SKILL.md` folders with progressive disclosure; the agent can `create_skill` at runtime (Voyager-style).\n- **Skills hub** — search and install community skills from GitHub or a URL, gated by a security scanner (threat patterns + structural + invisible-unicode) and a trust policy, with quarantine, a provenance lockfile, and an audit log.\n- **Command palette** — the interactive TUI has slash commands (`/help`, `/tools`, `/skills`, `/model`, `/sandbox`, …) with autocomplete and a live status bar.\n- **Knowledge (OKF)** — a Markdown concept bundle ([Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)) the agent reads and authors.\n- **Memory** — flat-file episodic lessons (`remember`/`recall`), strict-write.\n- **Prompt compression** — real [LLMLingua](https://github.com/microsoft/LLMLingua) via a Python sidecar (opt-in).\n- **Sandboxing** — env scrubbing always on; bubblewrap OS isolation (network off) with graceful degradation.\n- **Subagents** — `delegate` runs isolated subagents for independent, parallel investigation.\n- **MCP connectors** — connect to Model Context Protocol servers and use their tools.\n- **Multi-turn** — an interactive Ink TUI and a Hermes-style Web UI, both with session persistence, on one shared engine.\n- **Reliable** — retries with backoff, request timeouts, optional model fallback, usage reporting.\n\n## Install & run\n\n```bash\npnpm install\nexport OLLAMA_API_KEY=... # from https://ollama.com\n\npnpm dev \"summarize this project\" # one-shot task\npnpm dev # interactive TUI (multi-turn chat)\npnpm web # web UI at http://localhost:4100\n```\n\nBuild a distributable CLI:\n\n```bash\npnpm build\nnode dist/cli.js \"your task\" # or: caduceus \"your task\" / caduceus-web\n```\n\nThe CLI and the web server drive the same headless engine (`src/engine/session.ts`, via `run()` and `Conversation`).\n\n### Skills hub\n\nInstall community skills, with a security scan and recorded provenance:\n\n```bash\ncaduceus skills search pdf # search GitHub taps + catalog\ncaduceus skills inspect anthropics/skills/skills/pdf\ncaduceus skills install anthropics/skills/skills/pdf # scan, confirm, install\ncaduceus skills install https://example.com/SKILL.md # single-file skill from a URL\ncaduceus skills list # installed skills + provenance\ncaduceus skills audit # the install audit log\ncaduceus skills tap add owner/repo # add a custom GitHub source\n```\n\nTrusted repos (`anthropics/skills`, `openai/skills`) may install `caution`-rated skills; community sources are blocked on any finding unless you pass `--force`. State lives in `/.hub/` (lockfile, audit log, taps, quarantine). Set `GITHUB_TOKEN` to raise GitHub's rate limit.\n\n## Configuration\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `OLLAMA_API_KEY` | _required_ | Ollama Cloud API key |\n| `OLLAMA_BASE_URL` | `https://ollama.com/v1` | OpenAI-compatible endpoint |\n| `CADUCEUS_MODEL` | `qwen3.5:397b` | Model id |\n| `CADUCEUS_FALLBACK_MODEL` | _unset_ | Model tried once if the primary keeps failing |\n| `CADUCEUS_MAX_STEPS` | `20` | Loop iteration budget |\n| `CADUCEUS_TEMPERATURE` | `0` | Sampling temperature |\n| `CADUCEUS_RETRIES` | `3` | Attempts per request (backoff on 429/5xx/network) |\n| `CADUCEUS_TIMEOUT_MS` | `120000` | Per-attempt request timeout |\n| `CADUCEUS_STREAM` | `0` | `1` streams the model's output live |\n| `CADUCEUS_APPROVAL` | `prompt` if interactive, else `allow` | Gate risky shell commands: `allow` / `deny` / `prompt` |\n| `CADUCEUS_SANDBOX` | `auto` | `off` / `auto` / `on` (require bwrap) |\n| `CADUCEUS_SANDBOX_NET` | `0` | `1` to allow network inside the sandbox |\n| `CADUCEUS_COMPRESS` | `0` | `1` compresses large tool output via LLMLingua |\n| `CADUCEUS_SKILLS_DIR` / `_KNOWLEDGE_DIR` / `_MEMORY_DIR` / `_ARTIFACTS_DIR` | `skills` / `knowledge` / `memory` / `artifacts` | Where each layer lives |\n| `CADUCEUS_MCP_CONFIG` | `.caduceus/mcp.json` | MCP servers config |\n\nCLI flags `--model` and `--max-steps` override the environment.\n\n## Design and research\n\nBefore any code, two rounds of research established the design. The three\nfindings that shaped the system:\n\n- Single agent, not multi-agent: error amplification rises with decentralization,\n and multi-agent systems degrade on coding benchmarks where single-agent\n baselines already exceed 45%.\n- The scaffold is the product: the same model swings about 30 points on GAIA\n purely from context and tool-call management.\n- Context is a tiered, file-like store assembled per turn: Google's ADK guidance,\n Google Cloud's context model, and a file-system-abstraction paper converge on\n this shape.\n\n[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) maps each part of the system to the\nresearch that motivated it; [docs/REFERENCES.md](docs/REFERENCES.md) lists the\nsources.\n\n## Slack Connectivity\nSlack Integrations is built and tested successfully. The agent perform really well with web, cli and slack gateway. every trigger in the specific trigger will start a new thread and each slack thread is a new session. Establishing slack gateway requires the user to setup a slack app, and set necessary credentials such as the bot token, app token etc in the env file.\n\"image\"\n\nOutput : \n\niOS themed calculator application with accurate calculations\n\n\"image\"\n\n## Benchmarks\n\nThe standard for a result here is a fair, reproducible measurement with equal\ninformation given to every condition. Full details, caveats, and a retracted\nresult are in [docs/BENCHMARKS.md](docs/BENCHMARKS.md).\n\n**SWE-bench Verified** — real GitHub bugs from major Python projects, scored by\nthe official Docker grader (the agent runs inside each task's environment and\nmust make the project's own hidden tests pass). On a random sample of 15\ninstances with an open model (`glm-5.1`), Caduceus resolved **6/15 ≈ 40%** (95%\nCI 19.8–64.3%). A sampled estimate, not a full-500 score; run it via\n[`.github/workflows/swebench-bench.yml`](.github/workflows/swebench-bench.yml).\n\nPrompt compression with the real LLMLingua-2 model, measured in the agent loop on\na large prose-context task (read a long note, report one planted fact):\n\n![LLMLingua compression in the loop](docs/assets/llmlingua-loop.svg)\n\nModel tokens for the task fell 32% (4035 to 2727) and the planted fact was still\nreported correctly. Standalone, the README compressed 52% (765 to 367 tokens).\nCompression is lossy and prose-oriented, so it is opt-in and size-gated, not on\nby default. Reproduce with `pnpm measure:compress` and `pnpm compress`.\n\n## Development\n\n```bash\npnpm typecheck # tsc --noEmit\npnpm lint # eslint\npnpm test # vitest\npnpm build # tsup to dist/\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n", "bytes": 9762, "sha": "4e49755208492c0690e081984f7a7f24c4339ece038daa245c4a648e6342df09", "repo_slug": "tskvenkat/caduceus", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/okf_tskvenkat_caduceus_knowledge_index_md_fb8e81ba/readme" }