caveman

🐚 Seahorse — advisor→executor orchestration for Claude Code

Seahorse turns Claude Code into an advisor→executor orchestration layer: one architect model plans, cheaper specialist models build, every unit of work is routed to the model that does it best — under a strict token diet, over a live project knowledge graph, with typeset output.

Seahorse = the whole framework this repo installs. The token-discipline layer (caveman = talk less, ponytail = write less code) ships vendored in vendor/.

What it wires together

Concern	Tooling
Talk less / write less code	caveman + ponytail (vendored, MIT)
Plan → delegate → verify	Fable advisor → Sonnet/Opus executors → GPT (Codex) review
Research	/research, /deep-research, dynamic Workflows, arXiv (alphaXiv MCP), primary sources
Knowledge graph	graphify → OKF
Hold work across turns	/goal, /workflows
Outputs	PDFs = LaTeX/tectonic, diagrams = Mermaid
CI/CD	GitHub Actions templates (lint → type → test → build)

See docs/architecture.md for the flow diagrams and the full routing table.

Install

Seahorse ships two ways, because Claude Code has two extension models and each has a trade-off.

A. As a plugin (shareable, versioned) — skills are namespaced /seahorse:seahorse

claude plugin marketplace add Archit3115/seahorse
claude plugin install seahorse@seahorse
# optional companion token-discipline plugins (vendored in this repo):
claude plugin install caveman@seahorse ponytail@seahorse

Or ask Claude to do it for you after cloning — those are the two commands it runs.

Auto-install on clone: this repo carries a .claude/settings.json that pre-registers the marketplace and enables the plugins. When you open Claude Code inside the cloned repo and trust the folder, Claude Code can offer to install them without you typing the commands. This only affects sessions started in this directory, and — being third-party code — it still asks for your consent. There is no silent install-on-git clone; that would be a security hole, and Claude Code does not do it. If your version doesn't prompt, run the two commands above.

Local dev without installing: claude --plugin-dir /path/to/seahorse.

B. As standalone ~/.claude config — gives you the bare /seahorse command

Plugin skills are always namespaced (/seahorse:seahorse). If you want the bare /seahorse, run the installer, which copies the contract, agents, and commands into ~/.claude:

./install.sh

It merges (never clobbers) your global CLAUDE.md, installs the four agents and four commands (including the bare /seahorse), and wires the SessionStart bootstrap hook. Optional tooling it points you at: tectonic (LaTeX PDFs), uv + graphifyy (knowledge graph), codex CLI + codex login (GPT review).

Which to pick: plugin for clean, versioned, shareable install; installer if you specifically want the bare /seahorse and the global contract. They coexist — a --plugin-dir copy wins for its session.

Layout

seahorse/
├── .claude-plugin/
│   ├── plugin.json                # plugin manifest (the seahorse plugin)
│   └── marketplace.json           # marketplace: seahorse + vendored caveman + ponytail
├── .claude/settings.json          # auto-install pre-config (trust-prompt, this dir only)
├── commands/                      # /seahorse · /research · /kg · /pdf  (namespaced under the plugin)
├── agents/                        # advisor · researcher · builder-heavy · builder-light
├── hooks/
│   ├── hooks.json                 # plugin SessionStart hook
│   ├── seahorse-activate.sh       # injects the compact operating contract
│   └── seahorse-bootstrap.sh      # standalone-install project-bootstrap signal (gated to ~/Work)
├── contract/
│   ├── CLAUDE.global.md           # → ~/.claude/CLAUDE.md (standing contract)
│   ├── CLAUDE.project.template.md # per-project contract template
│   └── settings.snippet.json      # SessionStart hook snippet for the standalone install
├── vendor/                        # caveman + ponytail forks (MIT, attribution preserved)
├── benchmarks/                    # SWE-bench harness: Fable vs Opus vs Sonnet vs Seahorse
├── docs/architecture.md           # Mermaid diagrams + routing table
├── templates/ci/                  # node.yml · python.yml
└── install.sh                     # standalone ~/.claude installer

How a task flows