Catalyst

Terminal-based AI coding agent. Like Claude Code, but as a standalone CLI tool — and it can run fully offline on a local LLM via Ollama, or against the Claude API.

Requirements

• Node.js 18 or newer (needed for built-in fetch) — check with node -v
• npm (comes with Node)

Setup

Step 1: Install dependencies

cd catalyst
npm install

Step 2: Choose a mode

Option A — Run fully local (no API key, no internet, no cost)

1. Install Ollama for your OS (Mac/Windows/Linux installers on their site).
2. Pull a coding-capable model:

   ollama pull llama3.1
   # or a smaller/faster one:
   ollama pull qwen2.5-coder

3. Make sure Ollama is running (it usually starts automatically; if not: ollama serve).
4. Run Catalyst in local mode:

   CATALYST_PROVIDER=ollama npm run dev

   To use a specific model:

   CATALYST_PROVIDER=ollama CATALYST_MODEL=qwen2.5-coder npm run dev

Option B — Run against Claude API (cloud, needs API key)

export ANTHROPIC_API_KEY="your-key-here"
export CATALYST_PROVIDER=claude
npm run dev

Step 3 (optional): Make it stick without retyping env vars

Add to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export CATALYST_PROVIDER=ollama
export CATALYST_MODEL=llama3.1

Then just run npm run dev from now on.

Switching Providers

| Env Var | Values | Purpose | |---|---|---| | CATALYST_PROVIDER | ollama (default), local, or claude | Which backend to use | | CATALYST_MODEL | any model name | Overrides the default model for the chosen provider | | CATALYST_OLLAMA_URL | URL, default http://localhost:11434 | Where Ollama is running | | CATALYST_CONTEXT_TOKENS | Ollama context size, default 16384 | More room for larger codebases | | CATALYST_MAX_TOKENS | Claude output limit, default 8192 | More room for complete edits | | CATALYST_TEMPERATURE | default 0.2 | Lower values improve coding determinism | | CATALYST_MASCOT | off to disable | Hide the terminal pet | | CATALYST_MAX_ITERATIONS | default 25 | Maximum agent actions per task | | CATALYST_REQUEST_TIMEOUT | Ollama timeout, default 120000 ms | Prevent stuck local-model requests | | CATALYST_MODEL_RETRIES | default 2 | Retry transient model failures | | ANTHROPIC_API_KEY | your key | Required only for CATALYST_PROVIDER=claude |

Recommended Local Models

| Model | Size | Notes | |---|---|---| | llama3.1 | ~4.7GB | Good general default | | qwen2.5-coder | ~4.7GB (7B) | Strong at code specifically | | deepseek-coder-v2 | ~8.9GB | Larger, more capable, needs more RAM | | codellama | ~3.8GB | Meta's code-focused model |

Pull any with ollama pull <name>. Bigger models are smarter but slower and need more RAM (aim for 8GB+ free RAM for 7B-class models).

Commands

• /run <cmd> - Execute shell commands
• /test - Run tests
• /lint - Run the configured project linter
• /format - Run the configured formatter with approval
• /build - Run the configured build script with approval
• /fix - Debug and fix errors
• /files - Browse project files
• /search <text> - Search project source with line numbers
• /find <pattern> - Find files by glob pattern
• Search skips binary and very large files to keep results responsive
• /context - Show AI context
• /context list - List context paths
• /context clear - Clear all selected context
• /read <file> - Display file contents
• /tree - Show project structure
• /status - Show Git working-tree status
• /diff [file] - Show unstaged Git diff
• /review [focus] - Ask the model to review unstaged changes
• /undo - Restore the last file change in the current session
• /mode plan - Preview the next agent action without executing it
• /model <name> - Switch AI model
• /history - Show past tasks
• Sessions saved with /save are restored automatically on startup
• /help - Show commands
• /clear - Clear screen
• /exit - Exit Catalyst

Development

npm run dev          # Run with ts-node
npm run web          # Start the local Web UI at http://127.0.0.1:3417
npm run dev -- "fix the failing tests"  # Run one task and exit
npm run dev -- --web --port 3418        # Start the Web UI on a custom port
npm run dev -- --model qwen2.5-coder "fix the failing tests"  # Choose options at launch
npm run build        # Compile TypeScript
npm test             # Run core regression tests
npm start            # Run compiled version

Architecture

• CLI: readline-based interactive loop with lightweight startup flags
• Web UI: built-in local browser interface with streaming chat, slash commands, agent tasks, and browser approvals
• Agent: iterative tool loop with permissions, context compaction, retries, and recovery
• AI: Anthropic SDK for Claude API or Ollama for local models
• Workspace: safe file operations, glob/search, unified patches, undo checkpoints, and Git inspection
• Output: Chalk terminal output with optional pixel-art mascot
• Agent tools: project search, targeted exact-match edits, bounded command output, and malformed-action recovery
• The agent can ask clarifying questions and delete files only after approval
• The agent supports safe multi-hunk unified patches with context validation
• Follow-up agent tasks retain a compact memory of recent actions during the session
• Long-running agent commands stream output live while retaining bounded logs for diagnosis
• Press Ctrl+C once to cancel a running shell command without leaving Catalyst
• Long agent and chat sessions compact older history to preserve current-task context
• Normal chat is aware of the project tree and repository instruction files
• /test detects common project test runners (npm, pytest, Go, Cargo, and Make)
• Agent tasks automatically load supported CATALYST.md, CLAUDE.md, and AGENTS.md guidance from the project root and nested source areas

Deliberate non-goals

Catalyst focuses on a compact terminal coding workflow. Large UI rewrites, broad integration catalogs, and parallel subagent orchestration are intentionally not part of the default experience until they solve a demonstrated project need.