Alpha Agent

A local coding agent CLI. Talks to your files, runs commands, commits to git, and stays out of your way. No SaaS, no telemetry, no token in our pocket — your API keys, your machine.

╭───────────────────────────────────────────────────────╮
│ ✻ Alpha Agent  · local coding agent                   │
│                                                       │
│ Workspace  D:\projects\my-app                         │
│ Agent      auto-route · deepseek, kimi, zai           │
│ Chat       deepseek:deepseek-v4-flash · thinking: off │
│ Session    new (2026-05-13-…)                         │
╰───────────────────────────────────────────────────────╯

Highlights

• Three providers out of the box. DeepSeek v4, Kimi K2.6, Z.ai GLM-5.1 — all OpenAI-compatible tool calling, all streaming. Bring any subset; auto-routing handles the rest.
• Auto-routing. Each task is classified (frontend / backend / cli / review / general) and dispatched to the strongest available model for that category.
• Real agent tools. read_file (line-ranged + numbered), edit_file (uniqueness-checked, with diff preview + post-edit verification), write_file, run_command (timeout + abort), search, list_files, git_status/diff/log/commit, http_request, spawn_process/process_logs/list/kill, write_todos, dispatch_agent (subagent), plus profile-gated WordPress / Shopify / Laravel tools, and any MCP server you wire in.
• Image input. /image attaches a clipboard screenshot or file path to your next prompt. Drag-drop image paths into the terminal are auto-attached. All three providers accept multimodal content.
• Project profiles. Auto-detects 16 project types with the deepest support for the PHP-agencies wedge:
  • WordPress (up to 19 conditional tools: hook search both directions, wp_db_query via wp-cli, REST + enqueue audits, 17-check wp_plugin_audit, multisite-aware, ecosystem detection for WooCommerce / ACF / Elementor / form plugins, plus php -l + PHPCS auto-feedback after PHP edits).
  • Shopify (6 tools: liquid_find_renders, liquid_schema_summary, shopify_settings_summary, liquid_audit security scan, shopify_admin_query for read-only Admin GraphQL, liquid_section_groups, plus shopify theme check auto-feedback after .liquid edits).
  • Laravel (5 tools: laravel_find_routes, laravel_model_summary with relationships + mass-assignment safety check, laravel_route_list via php artisan route:list --json, laravel_env_summary with secret redaction, read-only laravel_tinker, plus PHPStan/Larastan auto-feedback).
  • Plus PHP/Composer, Django, Rails, Go, Rust, Spring Boot, FastAPI, Phoenix, SvelteKit, Astro, Next.js, React, Vue. The agent gets project-specific guidance and specialized tools without any configuration.
• Sessions and memory. Conversations persist per-workspace and resume across runs. AlphaAgent.md is loaded as project memory automatically. Auto-compaction keeps long sessions within the model's context window.
• Safety rails. Every destructive action gets a y/N approval with diff preview. /allow rules skip repeat prompts. Snapshot-based /rollback reverses edits — works in non-git workspaces too.
• MCP support. Drop a .alpha-agent/mcp.json and any stdio MCP server becomes available as agent tools (namespaced <server>__<tool>).
• Built-in eval harness. npm run eval runs 43 tasks × N models in sandbox dirs (19 general/frontend/backend/cli/review/planning + 8 WordPress + 11 Shopify + 5 Laravel), scores them, and prints a cost-per-pass comparison. Current results across DeepSeek v4-pro + Kimi K2.6 + Z.ai GLM-5.1 + auto-routing: 96/96 pass on stack-specific tasks, ~$0.013 per task pass average.
• Cost tracking. Pulls actual usage from the provider's streaming response when available, falls back to estimation. /cost and the eval summary show $.

Install

Requires Node 20+ and ideally ripgrep on PATH (search falls back to a manual walker if missing — slower).

npm install -g alpha-agent
# or run without installing:
npx alpha-agent

Set at least one API key:

export DEEPSEEK_API_KEY="sk-..."
export KIMI_API_KEY="sk-..."
export ZAI_API_KEY="..."

Or drop them in a .env file in the directory you launch from.

Quick start

Interactive REPL:

cd ~/projects/my-app
alpha-agent

> what does this project do?
> fix the bug in src/db.ts that returns negative numbers
> add a /health endpoint and commit it as "feat: add health check"

One-shot mode (no REPL, great for scripts and CI):

# quick chat
alpha-agent --ask "what's in package.json's scripts?"

# full agent task with auto-approve
alpha-agent --task "bump the version to 1.0.0 and commit" -y

# read prompt from stdin
echo "summarize the architecture" | alpha-agent --task -

# point at any workspace
alpha-agent --workspace ~/some-other-repo --task "..." -y

REPL commands

| Section | Command | Notes | |---|---|---| | Workspace | /cd <folder> | switch root; reloads profiles, MCP, memory | | | /ls, /search <q>, /read <file>, /pwd | direct workspace inspection | | Agent | /ask <q> | quick chat, no tools | | | (plain text) | run agent mode | | | /setup | scan project, build AlphaAgent.md memory | | Models | /models, /providers | list models / key status | | | /model agent kimi:kimi-k2.6 | set agent model explicitly | | | /route on\|off | toggle auto-routing | | | /thinking off\|high\|max | reasoning mode (DeepSeek/Z.ai/Kimi K2-thinking) | | Sessions | /sessions, /resume <n>, /new | persist, list, switch | | | /context, /cost | usage and $ | | | /rollback [n] | undo file edits via snapshot | | Permissions | /allow run_command:npm * | auto-approve matching prompts | | | /deny ..., /permissions, /forget <n> | | | Extensions | /mcp, /mcp reconnect | MCP servers | | | /profile | detected project profiles | | Eval | /eval [filter] | run benchmark suite | | Session | /help, /clear, /exit | |

Configuration

Per-workspace files (all under .alpha-agent/, all gitignored by default):

• AlphaAgent.md — project memory, auto-loaded as system-prompt context every run. Run /setup to bootstrap it.
• mcp.json — MCP server registrations:

  {
    "servers": {
      "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
    }
  }

• sessions/ — conversation history.
• history/ — file snapshots for /rollback.

Env-var overrides:

| Var | Effect | |---|---| | ALPHA_AGENT_MODEL | default agent model (e.g. deepseek-v4-pro) | | ALPHA_AGENT_CHAT_MODEL | default chat model | | ALPHA_AGENT_THINKING | off | high | max | | ALPHA_AGENT_AUTOROUTE | off to disable auto-routing | | ALPHA_AGENT_DEBUG=1 | dump API requests + SSE events to stderr | | AGENT_WORKSPACE | force workspace root | | NO_COLOR=1 / FORCE_COLOR=1 | terminal color control |

Architecture (short)

bin/alpha-agent.mjs     — published-package entry shim (uses tsx.tsImport)
cli/
  deep-code.ts          — REPL, agent loop, slash commands, tool dispatch
  ui.ts                 — terminal colors, spinner, diff colorization
core/
  providers.ts          — OpenAI-compatible streaming + per-provider config
  routing.ts            — task classifier + provider preferences
  workspace.ts          — sandboxed FS, rg search, path safety
  sessions.ts           — persistent conversation storage
  compaction.ts         — auto-summarize older turns at 70% context
  mcp.ts                — stdio JSON-RPC MCP client
  project-profile.ts    — WP/PHP/React detection + specialized tools
  snapshots.ts          — per-edit file backup for /rollback
  permissions.ts        — /allow glob rules with deny/allow precedence
  pricing.ts            — per-model USD/1M-tokens lookup
  git.ts                — subprocess wrapper for git
  eval.ts               — verifier types and sandbox setup
evals/tasks.ts          — benchmark task definitions

See CLAUDE.md for the detailed architecture map.

Eval

alpha-agent --eval                 # full matrix
alpha-agent --eval frontend        # one category
alpha-agent --eval bump-version    # one task
alpha-agent --eval _ deepseek      # one provider

Each run scores: pass/fail (via in-task verifier), rounds, duration, tool errors, billed tokens, estimated cost. Per-run JSON saved to evals/results/<timestamp>.json.

License

MIT (or whatever you put here — choose your license).