Cathead Coding

A capable coding agent with soft paws and sharp tools.

Cathead Coding is an open-source, Gemini-ready coding agent CLI powered by DeepSeek Harness. It keeps the product experience small and friendly while delegating the difficult parts—agent execution, tools, sessions, sandboxing, and model routing—to DSH.

Important

Cathead Coding is an early developer preview. Run it in a version-controlled workspace and review generated changes.

Why it purrs

• Interactive multi-turn terminal chat
• Input queue while the agent is working, plus next-tool-boundary steering
• Esc cancellation that stops the current turn without leaving the session
• Non-interactive run mode for scripts and CI
• Bounded autonomous goals with /auto (16 rounds or 30 minutes)
• Gemini through DSH's provider-neutral llm-pi-ai adapter
• Workspace-write file and shell sandbox
• Durable local sessions with --resume and workspace-aware --continue
• Live streaming, tool activity, approvals, and user questions
• Terminal-native Markdown for headings, code blocks, lists, task lists, tables, and links
• Plan mode with rendered review, Todo progress, token/context pressure, and auto-compaction
• Model switching, session search/rename/fork, Git worktree status, and background job views
• In-process and forked subagents with live “cat team” status
• Workspace instruction and local Skill discovery

Requirements

• Node.js 22.19 or newer
• pnpm 10 or newer
• A Gemini API key
• macOS or Linux for the current sandboxed Bash runtime

Let the cat in

git clone https://github.com/catyans/cathead-coding.git
cd cathead-coding
pnpm install
pnpm build
npm link

export GEMINI_API_KEY="your-key"
node dist/cli.js doctor
cathead --cwd /path/to/project

Start with a task:

cathead "fix the failing tests"

Run without the interactive UI:

cathead run --cwd /path/to/project "review the current diff"

Stream machine-readable events:

cathead --cwd /path/to/project run --output jsonl "run the tests"

Resume the latest session for a workspace, or an exact session:

cathead --cwd /path/to/project --continue
cathead --cwd /path/to/project --resume session-abc123

GOOGLE_GENERATIVE_AI_API_KEY is accepted as an alias for GEMINI_API_KEY. Secrets are inherited by the private DSH runtime subprocess and are never written into the Cordis configuration.

Configuration

Environment variable	Default	Purpose
GEMINI_API_KEY	—	Gemini authentication
CATHEAD_PROVIDER	google	DSH provider route
CATHEAD_MODEL	gemini-2.5-flash	Model id
CATHEAD_SESSION_ROOT	~/.cathead/sessions	Durable DSH sessions
CATHEAD_QUERY_PATH	~/.cathead/*.sqlite	Derived local session-search index
CATHEAD_DSH_CONFIG	bundled config	Alternate Cordis runtime composition

The default runtime is declared in config/cordis.yml. This explicit composition is the product boundary between Cathead Coding and DSH; deployments can replace it without forking either project.

Interactive controls

Input	Behavior
Input	Behavior
--------------------------------	-----------------------------------------------------------
Enter	Send now, or queue as the next turn while Cathead is busy
Shift-Enter / Ctrl-Enter	Insert a newline in the composer
Alt-Enter	Steer at the next tool boundary
↑ / ↓	Browse prompt history
PageUp / PageDown	Page through blocks in the latest Markdown answer
Esc	Cancel the current turn; the interactive session stays open
Ctrl-C	Cancel while busy; press twice while idle to exit
Ctrl-D	Exit while the input is empty
/plan [task] / /plan off	Enter planning mode, optionally with a task, or leave it
/compact	Compact eligible conversation history
/auto <objective>	Start a goal capped at 16 rounds or 30 minutes
/continue [guidance]	Add another bounded goal tranche
/pause / /cancel	Pause an auto goal or cancel the current turn
/queue / /steer <text>	Inspect queued work or inject guidance
/sessions [query]	List or search durable sessions
/rename <title> / /fork	Rename or fork the current session
/models / /model <route>	List models or switch provider/model and reasoning effort
/context / /diff / /agents	Inspect token usage, Git state, or the subagent team
/clear / /exit	Clear the view or close Cathead

Assistant replies and plan reviews are rendered as terminal-native Markdown. Images do not attempt to draw sixels or Kitty graphics; Cathead shows their alt text and path/URL so output remains portable.

Interactive mode intentionally requires a real TTY. Use cathead run for pipes, task runners, logs, and CI; Cathead will never silently turn an interactive invocation into a one-shot request.

Architecture

Terminal UI / run command
          │
          ▼
Cathead session controller
          │ private NDJSON bridge over stdio
          ▼
DSH Host ApiProxy + Cordis composition
          │
          ├── Gemini provider
          ├── agent spine
          ├── workspace sandbox
          ├── filesystem + Bash tools
          ├── plans, goals, Todo, compaction, and token meter
          ├── background jobs + subagent providers
          ├── approval/question providers
          └── durable sessions + projection cache

The controller owns one long-lived DSH session and folds its event stream into durable transcript state, temporary streaming state, tool activity, queue state, goals, and interactions. A model turn becoming idle does not unmount the UI or close the runtime. See docs/architecture.md for the lifecycle and clean-room design boundary.

Safety model

The built-in policy confines filesystem and shell writes to the selected workspace. Requests for wider access are surfaced as explicit interactive approvals. Headless runs reject interactive requests and exit with status 2. Automatic goals are bounded and must be explicitly renewed. Sessions are stored below ~/.cathead by default; API keys are inherited by the private runtime process and are not persisted in project configuration.

Development

pnpm install
pnpm dev
pnpm check

See CONTRIBUTING.md before opening a pull request. Security reports follow SECURITY.md.

Roadmap

• Full-screen diff viewer and richer per-tool cards
• Keyboard-driven session/model picker overlays
• Fine-grained scrolling inside very large code blocks and subagent transcript panes
• Windows PowerShell composition

License

MIT