{"id":48142780,"url":"https://github.com/ashlrai/ashlrcode","last_synced_at":"2026-04-08T20:02:43.111Z","repository":{"id":348820880,"uuid":"1198914870","full_name":"ashlrai/ashlrcode","owner":"ashlrai","description":"Multi-provider AI coding agent CLI. 30 tools, 15 skills, MCP support, autopilot mode.","archived":false,"fork":false,"pushed_at":"2026-04-07T01:58:47.000Z","size":1028,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-07T19:02:50.069Z","etag":null,"topics":["ai","cli","coding-agent","grok","mcp","xai"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ashlrai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T22:10:06.000Z","updated_at":"2026-04-07T01:58:50.000Z","dependencies_parsed_at":"2026-04-06T18:00:35.226Z","dependency_job_id":null,"html_url":"https://github.com/ashlrai/ashlrcode","commit_stats":null,"previous_names":["ashlrai/ashlrcode"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ashlrai/ashlrcode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashlrai%2Fashlrcode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashlrai%2Fashlrcode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashlrai%2Fashlrcode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashlrai%2Fashlrcode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ashlrai","download_url":"https://codeload.github.com/ashlrai/ashlrcode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashlrai%2Fashlrcode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31571601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cli","coding-agent","grok","mcp","xai"],"created_at":"2026-04-04T16:54:24.527Z","updated_at":"2026-04-08T20:02:43.095Z","avatar_url":"https://github.com/ashlrai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AshlrCode (ac)\n\n**Multi-provider AI coding agent for the terminal.**\n\n[![Version](https://img.shields.io/badge/version-2.0.0-blue)]()\n[![Tests](https://img.shields.io/badge/tests-367%2B%20passing-green)]()\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)]()\n[![Runtime](https://img.shields.io/badge/runtime-Bun-black)]()\n[![License](https://img.shields.io/badge/license-MIT-green)]()\n\n**45+ tools | 18 skills | 42+ slash commands | 6 providers | 367+ tests | 130 source files**\n\n---\n\n## What is AshlrCode?\n\nAshlrCode 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.\n\n---\n\n## Install\n\n```bash\nbun install -g ashlrcode\n```\n\n\u003e **Requires [Bun](https://bun.sh) runtime.** Install Bun with `curl -fsSL https://bun.sh/install | bash`.\n\n```bash\nexport XAI_API_KEY=\"your-key\"\n\nac                          # interactive REPL\nac \"fix the login bug\"      # single-shot mode\nac --continue               # resume last session\nac --resume \u003cid\u003e            # resume specific session\nac --migrate                # import MCP servers, skills, and sessions from Claude Code\n```\n\n### From source\n\n```bash\ngit clone https://github.com/ashlrai/ashlrcode.git\ncd ashlrcode\nbun install\nbun link                    # makes 'ac' available globally\n```\n\n---\n\n## Features\n\n### Core\n\n- **Agent loop** — AsyncGenerator-based streaming with parallel tool execution\n- **Multi-provider failover** — automatic retry and provider switching on rate limits\n- **3-tier context compression** — autoCompact, snipCompact, contextCollapse\n- **Speculation** — speculative tool execution for faster responses\n- **Model patches** — per-model prompt adjustments for optimal behavior\n- **Global error handling** — uncaught exceptions caught with data loss prevention (session auto-save)\n- **Thinking display** — stream and display model reasoning/thinking tokens\n- **Effort levels** — low / normal / high controls response depth and token budget\n- **Session import** — import Claude Code sessions with `ac --migrate`\n- **Autopilot mode** — fully autonomous scan → fix → test → PR → merge pipeline\n\n### Tools (45+)\n\n| Category | Tools | Description |\n|----------|-------|-------------|\n| **File I/O** | Read, Write, Edit, NotebookEdit, LS | Read, write, and edit files with undo snapshots |\n| **Search** | Glob, Grep, ToolSearch | Pattern matching, regex search, tool discovery |\n| **Execution** | Bash, PowerShell | Shell execution with live streaming and timeouts |\n| **Web** | WebFetch, WebSearch, WebBrowser | HTTP requests, search engines, browser automation |\n| **Interaction** | AskUser, SendMessage | Structured user prompts, inter-agent messaging |\n| **Agents** | Agent, ListPeers | Parallel sub-agents, peer discovery |\n| **Tasks** | TaskCreate, TaskUpdate, TaskList, TaskGet, TodoWrite | Task boards with dependencies and ownership |\n| **Planning** | EnterPlan, PlanWrite, ExitPlan (via mode) | Read-only exploration then structured execution |\n| **Memory** | MemorySave, MemoryList, MemoryDelete | Persistent per-project context across sessions |\n| **Config** | Config | View and modify settings at runtime |\n| **Git** | EnterWorktree, ExitWorktree, Diff | Isolated worktree branches, diff inspection |\n| **Teams** | TeamCreate, TeamDelete, TeamList, TeamDispatch | Named teammate roles with task dispatch |\n| **Infrastructure** | LSP, Workflow, Snip, Sleep | Language server, reusable workflows, context trimming, polling |\n| **MCP** | ListMcpResources, mcp__*__* | External tool servers via Model Context Protocol |\n\n### Commands (42+)\n\n| Command | Description |\n|---------|-------------|\n| `/help` | List all commands |\n| `/cost` | Token usage and cost breakdown |\n| `/status` | Provider, context usage, session info |\n| `/model [name]` | Show or switch model (aliases: `grok-fast`, `sonnet`, `opus`, `local`) |\n| `/effort [level]` | Cycle or set effort level (low / normal / high) |\n| `/compact` | Run all 3 context compression tiers |\n| `/clear` | Clear conversation history |\n| `/history` | File change history with timestamps |\n| `/undo` | Revert last file change |\n| `/restore` | Show available file snapshots |\n| `/diff` | Git diff --stat |\n| `/git` | Recent git log |\n| `/plan` | Cycle mode (normal / plan / auto) |\n| `/tools` | List all registered tools |\n| `/skills` | List available slash-command skills |\n| `/sessions` | List saved sessions |\n| `/memory` | Show project memories |\n| `/buddy` | Buddy stats, species, rarity, level |\n| `/btw \u003cquestion\u003e` | Side question in sub-agent (no main context pollution) |\n| `/autopilot` | Autonomous scan / queue / approve / run / auto |\n| `/kairos \u003cgoal\u003e` | Start KAIROS autonomous mode |\n| `/trigger` | Scheduled triggers (add / list / toggle / delete) |\n| `/voice` | Voice input via Whisper (record / transcribe) |\n| `/sync` | Export / import settings across machines |\n| `/bridge` | Bridge server status (HTTP API for external tools) |\n| `/keybindings` | Show and customize keyboard shortcuts |\n| `/features` | Feature flag status |\n| `/patches` | Active model patches for current model |\n| `/undercover` | Toggle undercover mode (stealth prompts) |\n| `/remote` | Remote settings status |\n| `/telemetry` | Recent telemetry events |\n| `/quit` | Exit (also `/exit`, `/q`) |\n\nPlus **custom skills** loaded from `~/.ashlrcode/skills/*.md` — invoked as `/skill-name`.\n\n### Agent System\n\n- **Sub-agents** — spawn parallel agents for research, exploration, and independent tasks\n- **Worktree isolation** — agents work in git worktrees to avoid conflicts\n- **KAIROS autonomous mode** — heartbeat-driven loop with focus-aware autonomy levels\n- **Team dispatch** — named teammates with roles, dispatched to tasks\n- **IPC** — inter-process communication between agent instances\n- **Peer discovery** — agents find and message sibling instances\n\n### UX\n\n- **Ink-based UI** — React terminal rendering with bordered input box, context bar, and autocomplete\n- **Bordered tool result blocks** — tool output framed with colored diff highlighting (green/red)\n- **Slash command coloring** — commands highlighted in blue for quick visual scanning\n- **Buddy system** — persistent ASCII pet with species, moods, animated poses, hats, rarity, and stats\n- **Buddy animations** — mood-driven pose cycling with idle, thinking, celebrating, and confused states\n- **Keybindings** — customizable shortcuts, chord bindings, Shift+Tab mode switching\n- **Effort levels** — low / normal / high controls response depth\n- **Smart paste** — large clipboard pastes auto-collapsed in context\n- **Image support** — drag-and-drop images with base64 collapse\n- **Voice mode** — record and transcribe via Whisper\n- **Notifications** — system notifications on task completion\n\n### Persistence\n\n- **Sessions** — JSONL at `~/.ashlrcode/sessions/`, resume with `--continue` or `--resume`\n- **Dreams** — background memory consolidation when idle, loaded on next session\n- **File undo** — every Write/Edit snapshots the original, revert with `/undo`\n- **Settings sync** — export/import settings across machines with `/sync`\n- **Memory** — persistent per-project context loaded automatically\n\n### Security\n\n- **Permission system** — read-only tools auto-allowed; write tools prompt `[y]es / [a]lways / [n]o / [d]eny-always`\n- **Permission rules** — regex-based allow/deny rules in settings\n- **Hook system** — pre/post tool hooks can block, modify, or extend tool calls\n- **Undercover mode** — stealth prompt adjustments\n- **Input validation** — tool input schemas validated before execution\n- **macOS Keychain** — credential storage via macOS Keychain for API keys\n- **Global error handling** — uncaught exceptions and SIGTERM caught; sessions saved before exit to prevent data loss\n\n### Infrastructure\n\n- **Feature flags** — runtime toggles for experimental features\n- **Telemetry** — event logging for debugging and analytics\n- **Cost tracking** — per-provider token and cost accounting\n- **Retry with backoff** — rate limits (3x, 1s base), network errors (2x, 2s base)\n- **Speculation** — predictive tool execution\n- **LSP integration** — Language Server Protocol for diagnostics and completions\n- **MCP with SSE/WebSocket transport** — stdio, SSE, and WebSocket connections to external tool servers\n- **MCP OAuth** — OAuth flow for MCP server authentication\n- **Cron triggers** — scheduled recurring agent tasks\n- **IPC** — inter-process messaging between instances\n- **Bridge server** — HTTP API for external tool integration\n- **Remote settings** — fetch config overrides from a URL\n- **Model patches** — per-model prompt tuning\n\n---\n\n## MCP (Model Context Protocol)\n\nAshlrCode connects to external tool servers via MCP. Configure servers in `~/.ashlrcode/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@my-org/mcp-server\"],\n      \"env\": { \"API_KEY\": \"...\" }\n    },\n    \"remote-server\": {\n      \"url\": \"http://localhost:3000\"\n    },\n    \"chrome-extension\": {\n      \"url\": \"http://localhost:12007\",\n      \"env\": {}\n    }\n  }\n}\n```\n\n**Stdio transport** — spawns a local process and communicates over stdin/stdout. Use `command` + `args`.\n\n**SSE transport** — connects to a running HTTP server. Use `url`. Works with browser extensions like Claude-in-Chrome that expose an MCP endpoint.\n\n**WebSocket transport** — connects via WebSocket for bidirectional streaming. Use `url` with a `ws://` or `wss://` scheme.\n\n**OAuth** — for authenticated MCP servers, add an `oauth` block with `authorizationUrl`, `tokenUrl`, `clientId`, and `scopes`.\n\nMCP tools appear automatically as `mcp__\u003cserver\u003e__\u003ctool\u003e` and are available to the agent alongside built-in tools.\n\n---\n\n## Configuration\n\n| Path | Purpose |\n|------|---------|\n| `~/.ashlrcode/settings.json` | Providers, hooks, MCP servers, feature flags |\n| `~/.ashlrcode/keybindings.json` | Custom keyboard shortcuts |\n| `~/.ashlrcode/permissions.json` | Persisted tool permission rules |\n| `~/.ashlrcode/sessions/` | Saved conversation sessions (JSONL) |\n| `~/.ashlrcode/dreams/` | Background memory consolidation files |\n| `~/.ashlrcode/memory/` | Per-project persistent memories |\n| `~/.ashlrcode/tasks/` | Persisted task boards |\n| `~/.ashlrcode/skills/` | Custom skill definitions (`.md` files) |\n| `./ASHLR.md` or `./CLAUDE.md` | Project-level instructions |\n\n### Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `XAI_API_KEY` | xAI Grok API key (primary) |\n| `ANTHROPIC_API_KEY` | Anthropic Claude API key |\n| `OPENAI_API_KEY` | OpenAI API key (also used for Whisper voice) |\n| `DEEPSEEK_API_KEY` | DeepSeek API key |\n| `GROQ_API_KEY` | Groq API key |\n| `AC_BRIDGE_PORT` | Enable bridge server on this port |\n| `AC_REMOTE_SETTINGS_URL` | URL for remote settings fetch |\n| `AC_FEATURE_VOICE_MODE` | Enable voice input (`true`) |\n\n### Hook System\n\nPre/post tool execution hooks for automation and safety:\n\n```json\n{\n  \"hooks\": {\n    \"preToolUse\": [\n      { \"toolName\": \"Bash\", \"inputPattern\": \"rm -rf\", \"action\": \"deny\", \"message\": \"Blocked\" },\n      { \"toolName\": \"Bash\", \"inputPattern\": \"git push\", \"action\": \"ask\" }\n    ],\n    \"postToolUse\": [\n      { \"toolName\": \"Edit\", \"command\": \"bun run lint --fix $TOOL_INPUT\" }\n    ]\n  }\n}\n```\n\n---\n\n## Providers\n\n| Provider | Model | Cost (in/out per 1M tokens) | Context |\n|----------|-------|-----------------------------|---------|\n| **xAI** (default) | grok-4-1-fast-reasoning | $0.20 / $0.50 | 2M |\n| **Anthropic** | claude-sonnet-4-6 | $3.00 / $15.00 | 200K |\n| **OpenAI** | gpt-4o | $2.50 / $10.00 | 128K |\n| **DeepSeek** | deepseek-chat | $0.14 / $0.28 | 128K |\n| **Groq** | llama-3.3-70b | $0.59 / $0.79 | 128K |\n| **Ollama** (local) | any local model | Free | Model-dependent |\n\nAuto-failover on rate limits. Model aliases: `grok-fast`, `grok-4`, `grok-3`, `sonnet`, `opus`, `llama`, `local`.\n\n---\n\n## KAIROS Mode\n\nKAIROS is an autonomous agent mode with a heartbeat-driven loop. It detects terminal focus to adjust autonomy:\n\n- **Focused** — collaborative: asks before significant changes\n- **Unfocused** — full-auto: acts independently while you're away\n- **Unknown** — balanced default\n\n```bash\nac\n\u003e /kairos \"refactor the auth module and add tests\"\n\u003e /kairos stop\n```\n\n---\n\n## Buddy System\n\nEvery 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.\n\n```\n  ┌──────────────────────────────┐     c\\  /c\n  │ What if we tried a different │    ( .  . )\n  │ approach to the auth flow?   │    ( _nn_ )\n  └──────────────────────┐       │    (______)\n                         └───────┘     ||  ||\n```\n\nSpecies: penguin, cat, ghost, owl, robot, dragon, axolotl (epic), capybara (legendary). Stats: debugging, patience, chaos, wisdom, snark.\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/ashlrai/ashlrcode.git\ncd ashlrcode\nbun install\n\nbun run dev                 # watch mode\nbun run start               # run CLI\nbun test                    # 367+ tests, ~10s\nbunx tsc --noEmit           # type check\nbun run build               # bundle to dist/\n```\n\n### Architecture\n\n```\nsrc/                        # 130 source files\n├── cli.ts                  # Entry point + fallback REPL\n├── repl.tsx                # Ink-based terminal UI\n├── setup.ts                # Initialization and wiring\n├── agent/                  # Core agent loop, sub-agents, KAIROS, teams, dreams, IPC\n├── providers/              # xAI, Anthropic, router, retry, cost tracking\n├── tools/                  # 45+ tools (32 files)\n├── skills/                 # Skill loader + registry\n├── mcp/                    # MCP client, manager, OAuth, SSE transport\n├── planning/               # Plan mode + plan tools\n├── persistence/            # Sessions + memory\n├── config/                 # Settings, hooks, permissions, features, sync, undercover\n├── state/                  # File history (undo)\n├── ui/                     # Ink components, buddy, speech bubbles, theme, effort\n├── autopilot/              # Scanner + work queue\n├── bridge/                 # HTTP bridge server + client\n├── telemetry/              # Event logging\n└── voice/                  # Voice input via Whisper\n```\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashlrai%2Fashlrcode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashlrai%2Fashlrcode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashlrai%2Fashlrcode/lists"}