Ashlrcode

AshlrCode (ac)

Multi-provider AI coding agent for the terminal.

[]() []() []() []() []()

45+ tools | 18 skills | 42+ slash commands | 6 providers | 367+ tests | 130 source files

---

What is AshlrCode?

AshlrCode is an open-source AI coding agent CLI built as an alternative to Claude Code. It runs multi-provider LLM conversations with tool use in your terminal — powered by xAI Grok by default, with failover to Anthropic, OpenAI, DeepSeek, Groq, and Ollama. It ships with 45+ built-in tools, 18 skills, an autonomous KAIROS mode, sub-agent orchestration, MCP server integration, and a persistent buddy companion.

---

Install

bun install -g ashlrcode

> Requires Bun runtime. Install Bun with curl -fsSL https://bun.sh/install | bash.

export XAI_API_KEY="your-key"

ac                          # interactive REPL
ac "fix the login bug"      # single-shot mode
ac --continue               # resume last session
ac --resume             # resume specific session
ac --migrate                # import MCP servers, skills, and sessions from Claude Code

From source

git clone https://github.com/ashlrai/ashlrcode.git
cd ashlrcode
bun install
bun link                    # makes 'ac' available globally

---

Features

Core

• Agent loop — AsyncGenerator-based streaming with parallel tool execution
• Multi-provider failover — automatic retry and provider switching on rate limits
• 3-tier context compression — autoCompact, snipCompact, contextCollapse
• Speculation — speculative tool execution for faster responses
• Model patches — per-model prompt adjustments for optimal behavior
• Global error handling — uncaught exceptions caught with data loss prevention (session auto-save)
• Thinking display — stream and display model reasoning/thinking tokens
• Effort levels — low / normal / high controls response depth and token budget
• Session import — import Claude Code sessions with ac --migrate
• Autopilot mode — fully autonomous scan → fix → test → PR → merge pipeline

Tools (45+)

| Category | Tools | Description | |----------|-------|-------------| | File I/O | Read, Write, Edit, NotebookEdit, LS | Read, write, and edit files with undo snapshots | | Search | Glob, Grep, ToolSearch | Pattern matching, regex search, tool discovery | | Execution | Bash, PowerShell | Shell execution with live streaming and timeouts | | Web | WebFetch, WebSearch, WebBrowser | HTTP requests, search engines, browser automation | | Interaction | AskUser, SendMessage | Structured user prompts, inter-agent messaging | | Agents | Agent, ListPeers | Parallel sub-agents, peer discovery | | Tasks | TaskCreate, TaskUpdate, TaskList, TaskGet, TodoWrite | Task boards with dependencies and ownership | | Planning | EnterPlan, PlanWrite, ExitPlan (via mode) | Read-only exploration then structured execution | | Memory | MemorySave, MemoryList, MemoryDelete | Persistent per-project context across sessions | | Config | Config | View and modify settings at runtime | | Git | EnterWorktree, ExitWorktree, Diff | Isolated worktree branches, diff inspection | | Teams | TeamCreate, TeamDelete, TeamList, TeamDispatch | Named teammate roles with task dispatch | | Infrastructure | LSP, Workflow, Snip, Sleep | Language server, reusable workflows, context trimming, polling | | MCP | ListMcpResources, mcp____ | External tool servers via Model Context Protocol |

Commands (42+)

| Command | Description | |---------|-------------| | /help | List all commands | | /cost | Token usage and cost breakdown | | /status | Provider, context usage, session info | | /model [name] | Show or switch model (aliases: grok-fast, sonnet, opus, local) | | /effort [level] | Cycle or set effort level (low / normal / high) | | /compact | Run all 3 context compression tiers | | /clear | Clear conversation history | | /history | File change history with timestamps | | /undo | Revert last file change | | /restore | Show available file snapshots | | /diff | Git diff --stat | | /git | Recent git log | | /plan | Cycle mode (normal / plan / auto) | | /tools | List all registered tools | | /skills | List available slash-command skills | | /sessions | List saved sessions | | /memory | Show project memories | | /buddy | Buddy stats, species, rarity, level | | /btw | Side question in sub-agent (no main context pollution) | | /autopilot | Autonomous scan / queue / approve / run / auto | | /kairos | Start KAIROS autonomous mode | | /trigger | Scheduled triggers (add / list / toggle / delete) | | /voice | Voice input via Whisper (record / transcribe) | | /sync | Export / import settings across machines | | /bridge | Bridge server status (HTTP API for external tools) | | /keybindings | Show and customize keyboard shortcuts | | /features | Feature flag status | | /patches | Active model patches for current model | | /undercover | Toggle undercover mode (stealth prompts) | | /remote | Remote settings status | | /telemetry | Recent telemetry events | | /quit | Exit (also /exit, /q) |

Plus custom skills loaded from ~/.ashlrcode/skills/*.md — invoked as /skill-name.

Agent System

• Sub-agents — spawn parallel agents for research, exploration, and independent tasks
• Worktree isolation — agents work in git worktrees to avoid conflicts
• KAIROS autonomous mode — heartbeat-driven loop with focus-aware autonomy levels
• Team dispatch — named teammates with roles, dispatched to tasks
• IPC — inter-process communication between agent instances
• Peer discovery — agents find and message sibling instances

UX

• Ink-based UI — React terminal rendering with bordered input box, context bar, and autocomplete
• Bordered tool result blocks — tool output framed with colored diff highlighting (green/red)
• Slash command coloring — commands highlighted in blue for quick visual scanning
• Buddy system — persistent ASCII pet with species, moods, animated poses, hats, rarity, and stats
• Buddy animations — mood-driven pose cycling with idle, thinking, celebrating, and confused states
• Keybindings — customizable shortcuts, chord bindings, Shift+Tab mode switching
• Effort levels — low / normal / high controls response depth
• Smart paste — large clipboard pastes auto-collapsed in context
• Image support — drag-and-drop images with base64 collapse
• Voice mode — record and transcribe via Whisper
• Notifications — system notifications on task completion

Persistence

• Sessions — JSONL at ~/.ashlrcode/sessions/, resume with --continue or --resume
• Dreams — background memory consolidation when idle, loaded on next session
• File undo — every Write/Edit snapshots the original, revert with /undo
• Settings sync — export/import settings across machines with /sync
• Memory — persistent per-project context loaded automatically

Security

• Permission system — read-only tools auto-allowed; write tools prompt [y]es / [a]lways / [n]o / [d]eny-always
• Permission rules — regex-based allow/deny rules in settings
• Hook system — pre/post tool hooks can block, modify, or extend tool calls
• Undercover mode — stealth prompt adjustments
• Input validation — tool input schemas validated before execution
• macOS Keychain — credential storage via macOS Keychain for API keys
• Global error handling — uncaught exceptions and SIGTERM caught; sessions saved before exit to prevent data loss

Infrastructure

• Feature flags — runtime toggles for experimental features
• Telemetry — event logging for debugging and analytics
• Cost tracking — per-provider token and cost accounting
• Retry with backoff — rate limits (3x, 1s base), network errors (2x, 2s base)
• Speculation — predictive tool execution
• LSP integration — Language Server Protocol for diagnostics and completions
• MCP with SSE/WebSocket transport — stdio, SSE, and WebSocket connections to external tool servers
• MCP OAuth — OAuth flow for MCP server authentication
• Cron triggers — scheduled recurring agent tasks
• IPC — inter-process messaging between instances
• Bridge server — HTTP API for external tool integration
• Remote settings — fetch config overrides from a URL
• Model patches — per-model prompt tuning

---

MCP (Model Context Protocol)

AshlrCode connects to external tool servers via MCP. Configure servers in ~/.ashlrcode/settings.json:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/mcp-server"],
      "env": { "API_KEY": "..." }
    },
    "remote-server": {
      "url": "http://localhost:3000"
    },
    "chrome-extension": {
      "url": "http://localhost:12007",
      "env": {}
    }
  }
}

Stdio transport — spawns a local process and communicates over stdin/stdout. Use command + args.

SSE transport — connects to a running HTTP server. Use url. Works with browser extensions like Claude-in-Chrome that expose an MCP endpoint.

WebSocket transport — connects via WebSocket for bidirectional streaming. Use url with a ws:// or wss:// scheme.

OAuth — for authenticated MCP servers, add an oauth block with authorizationUrl, tokenUrl, clientId, and scopes.

MCP tools appear automatically as mcp____ and are available to the agent alongside built-in tools.

---

Configuration

| Path | Purpose | |------|---------| | ~/.ashlrcode/settings.json | Providers, hooks, MCP servers, feature flags | | ~/.ashlrcode/keybindings.json | Custom keyboard shortcuts | | ~/.ashlrcode/permissions.json | Persisted tool permission rules | | ~/.ashlrcode/sessions/ | Saved conversation sessions (JSONL) | | ~/.ashlrcode/dreams/ | Background memory consolidation files | | ~/.ashlrcode/memory/ | Per-project persistent memories | | ~/.ashlrcode/tasks/ | Persisted task boards | | ~/.ashlrcode/skills/ | Custom skill definitions (.md files) | | ./ASHLR.md or ./CLAUDE.md | Project-level instructions |

Environment Variables

| Variable | Purpose | |----------|---------| | XAI_API_KEY | xAI Grok API key (primary) | | ANTHROPIC_API_KEY | Anthropic Claude API key | | OPENAI_API_KEY | OpenAI API key (also used for Whisper voice) | | DEEPSEEK_API_KEY | DeepSeek API key | | GROQ_API_KEY | Groq API key | | AC_BRIDGE_PORT | Enable bridge server on this port | | AC_REMOTE_SETTINGS_URL | URL for remote settings fetch | | AC_FEATURE_VOICE_MODE | Enable voice input (true) |

Hook System

Pre/post tool execution hooks for automation and safety:

{
  "hooks": {
    "preToolUse": [
      { "toolName": "Bash", "inputPattern": "rm -rf", "action": "deny", "message": "Blocked" },
      { "toolName": "Bash", "inputPattern": "git push", "action": "ask" }
    ],
    "postToolUse": [
      { "toolName": "Edit", "command": "bun run lint --fix $TOOL_INPUT" }
    ]
  }
}

---

Providers

| Provider | Model | Cost (in/out per 1M tokens) | Context | |----------|-------|-----------------------------|---------| | xAI (default) | grok-4.3 | $0.20 / $0.50 | 2M | | Anthropic | claude-sonnet-4-6 | $3.00 / $15.00 | 200K | | OpenAI | gpt-4o | $2.50 / $10.00 | 128K | | DeepSeek | deepseek-chat | $0.14 / $0.28 | 128K | | Groq | llama-3.3-70b | $0.59 / $0.79 | 128K | | Ollama (local) | any local model | Free | Model-dependent |

Auto-failover on rate limits. Model aliases: grok-fast, grok-4, grok-3, sonnet, opus, llama, local.

---

KAIROS Mode

KAIROS is an autonomous agent mode with a heartbeat-driven loop. It detects terminal focus to adjust autonomy:

• Focused — collaborative: asks before significant changes
• Unfocused — full-auto: acts independently while you're away
• Unknown — balanced default

ac
> /kairos "refactor the auth module and add tests"
> /kairos stop

---

Buddy System

Every user gets a deterministic ASCII pet companion based on a hash of their home directory. Eight species with rarity tiers, mood-based animations, equippable hats, and stats that grow with usage.

  ┌──────────────────────────────┐     c\  /c
  │ What if we tried a different │    ( .  . )
  │ approach to the auth flow?   │    ( _nn_ )
  └──────────────────────┐       │    (______)
                         └───────┘     ||  ||

Species: penguin, cat, ghost, owl, robot, dragon, axolotl (epic), capybara (legendary). Stats: debugging, patience, chaos, wisdom, snark.

---

Development

git clone https://github.com/ashlrai/ashlrcode.git
cd ashlrcode
bun install

bun run dev                 # watch mode
bun run start               # run CLI
bun test                    # 367+ tests, ~10s
bunx tsc --noEmit           # type check
bun run build               # bundle to dist/

Architecture

src/                        # 130 source files
├── cli.ts                  # Entry point + fallback REPL
├── repl.tsx                # Ink-based terminal UI
├── setup.ts                # Initialization and wiring
├── agent/                  # Core agent loop, sub-agents, KAIROS, teams, dreams, IPC
├── providers/              # xAI, Anthropic, router, retry, cost tracking
├── tools/                  # 45+ tools (32 files)
├── skills/                 # Skill loader + registry
├── mcp/                    # MCP client, manager, OAuth, SSE transport
├── planning/               # Plan mode + plan tools
├── persistence/            # Sessions + memory
├── config/                 # Settings, hooks, permissions, features, sync, undercover
├── state/                  # File history (undo)
├── ui/                     # Ink components, buddy, speech bubbles, theme, effort
├── autopilot/              # Scanner + work queue
├── bridge/                 # HTTP bridge server + client
├── telemetry/              # Event logging
└── voice/                  # Voice input via Whisper

---

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ashlrai
• Source: ashlrai/ashlrcode
• License: MIT
• Homepage: https://ashlr.ai/ashlrcode

Install and usage instructions live in the source repository linked above.