ashlrcode 1.0.0 → 2.1.0

package/README.md

@@ -2,36 +2,47 @@
 
 **Multi-provider AI coding agent for the terminal.**
 
-[![Version](https://img.shields.io/badge/version-1.0.0-blue)]()
-[![Tests](https://img.shields.io/badge/tests-335%20passing-green)]()
+[![Version](https://img.shields.io/badge/version-2.0.0-blue)]()
+[![Tests](https://img.shields.io/badge/tests-367%2B%20passing-green)]()
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)]()
 [![Runtime](https://img.shields.io/badge/runtime-Bun-black)]()
 [![License](https://img.shields.io/badge/license-MIT-green)]()
 
-**42 tools | 34 commands | 6 providers | 335 tests | 130 source files**
+**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 42 built-in tools, an autonomous KAIROS mode, sub-agent orchestration, and a persistent buddy companion.
+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.
 
 ---
 
-## Quick Start
+## Install
 
 ```bash
-git clone https://github.com/ashlrai/ashlrcode.git
-cd ashlrcode
-bun install
-bun link                    # makes 'ac' available globally
+bun install -g ashlrcode
+```
+
+> **Requires [Bun](https://bun.sh) runtime.** Install Bun with `curl -fsSL https://bun.sh/install | bash`.
 
+```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 <id>            # resume specific session
+ac --migrate                # import MCP servers, skills, and sessions from Claude Code
+```
+
+### From source
+
+```bash
+git clone https://github.com/ashlrai/ashlrcode.git
+cd ashlrcode
+bun install
+bun link                    # makes 'ac' available globally
 ```
 
 ---
@@ -45,8 +56,13 @@ ac --resume <id>            # resume specific session
 - **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 (42)
+### Tools (45+)
 
 | Category | Tools | Description |
 |----------|-------|-------------|
@@ -65,7 +81,7 @@ ac --resume <id>            # resume specific session
 | **Infrastructure** | LSP, Workflow, Snip, Sleep | Language server, reusable workflows, context trimming, polling |
 | **MCP** | ListMcpResources, mcp__*__* | External tool servers via Model Context Protocol |
 
-### Commands (34)
+### Commands (42+)
 
 | Command | Description |
 |---------|-------------|
@@ -115,8 +131,11 @@ Plus **custom skills** loaded from `~/.ashlrcode/skills/*.md` — invoked as `/s
 
 ### UX
 
-- **Ink-based UI** — React terminal rendering with input box, context bar, and autocomplete
-- **Buddy system** — persistent ASCII pet companion with species, moods, hats, rarity, and stats
+- **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
@@ -139,6 +158,8 @@ Plus **custom skills** loaded from `~/.ashlrcode/skills/*.md` — invoked as `/s
 - **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
 
@@ -148,6 +169,7 @@ Plus **custom skills** loaded from `~/.ashlrcode/skills/*.md` — invoked as `/s
 - **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
@@ -157,6 +179,41 @@ Plus **custom skills** loaded from `~/.ashlrcode/skills/*.md` — invoked as `/s
 
 ---
 
+## MCP (Model Context Protocol)
+
+AshlrCode connects to external tool servers via MCP. Configure servers in `~/.ashlrcode/settings.json`:
+
+```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__<server>__<tool>` and are available to the agent alongside built-in tools.
+
+---
+
 ## Configuration
 
 | Path | Purpose |
@@ -260,7 +317,7 @@ bun install
 
 bun run dev                 # watch mode
 bun run start               # run CLI
-bun test                    # 335 tests, 666 assertions, ~10s
+bun test                    # 367+ tests, ~10s
 bunx tsc --noEmit           # type check
 bun run build               # bundle to dist/
 ```
@@ -274,9 +331,9 @@ src/                        # 130 source files
 ├── setup.ts                # Initialization and wiring
 ├── agent/                  # Core agent loop, sub-agents, KAIROS, teams, dreams, IPC
 ├── providers/              # xAI, Anthropic, router, retry, cost tracking
-├── tools/                  # 42 tools (32 files)
+├── tools/                  # 45+ tools (32 files)
 ├── skills/                 # Skill loader + registry
-├── mcp/                    # MCP client, manager, OAuth
+├── mcp/                    # MCP client, manager, OAuth, SSE transport
 ├── planning/               # Plan mode + plan tools
 ├── persistence/            # Sessions + memory
 ├── config/                 # Settings, hooks, permissions, features, sync, undercover

package/package.json

@@ -1,29 +1,48 @@
 {
   "name": "ashlrcode",
-  "version": "1.0.0",
-  "description": "Multi-provider AI coding agent CLI — 42 tools, 34 commands, autonomous mode",
-  "module": "src/cli.ts",
+  "version": "2.1.0",
+  "description": "Multi-provider AI coding agent CLI — 45 tools, 40 commands, autonomous mode, verification agent, multi-agent coordination",
   "type": "module",
   "private": false,
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ashlrai/ashlrcode"
+    "url": "git+https://github.com/ashlrai/ashlrcode.git"
   },
-  "keywords": ["ai", "coding", "agent", "cli", "xai", "grok", "claude", "multi-provider", "autonomous"],
-  "files": ["src/", "README.md", "LICENSE"],
+  "keywords": [
+    "ai",
+    "coding",
+    "agent",
+    "cli",
+    "xai",
+    "grok",
+    "claude",
+    "multi-provider",
+    "autonomous"
+  ],
+  "files": [
+    "src/",
+    "!src/__tests__/",
+    "prompts/",
+    "README.md",
+    "LICENSE"
+  ],
   "bin": {
-    "ashlrcode": "./src/cli.ts",
-    "ac": "./src/cli.ts"
+    "ashlrcode": "src/cli.ts",
+    "ac": "src/cli.ts"
   },
   "scripts": {
     "dev": "bun run src/cli.ts",
     "test": "bun test",
     "build": "bun build src/cli.ts --compile --outfile dist/ac",
     "build:all": "bun build src/cli.ts --compile --outfile dist/ac-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "lint": "bunx @biomejs/biome check src/",
+    "lint:fix": "bunx @biomejs/biome check --write src/",
+    "format": "bunx @biomejs/biome format --write src/"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
     "@types/bun": "latest",
     "@types/react": "^19.2.14"
   },

package/prompts/skills/commit.md

@@ -0,0 +1,36 @@
+---
+name: commit
+description: Create a well-crafted git commit and push to GitHub
+trigger: /commit
+---
+
+Create a git commit for the current changes. Follow these steps:
+
+1. Run `git status` to see all changes and `git diff` to see the actual modifications.
+2. Run `git log --oneline -5` to match the repo's commit message style.
+3. Analyze ALL changes (staged and unstaged) and draft a commit message:
+   - Summarize the nature: new feature, bug fix, refactor, docs, etc.
+   - Focus on WHY, not WHAT
+   - Keep it concise (1-2 sentences)
+4. Stage specific files by name (NEVER use `git add -A` or `git add .`)
+5. Do NOT commit files that contain secrets (.env, credentials, API keys)
+6. Create the commit:
+
+```bash
+git commit -m "$(cat <<'EOF'
+Your commit message here.
+
+Co-Authored-By: AshlrCode <noreply@ashlr.ai>
+EOF
+)"
+```
+
+7. After commit, run `git status` to verify success.
+8. Push to remote if the user asked for it.
+
+IMPORTANT:
+- Always create NEW commits, never amend
+- Never skip hooks (--no-verify)
+- Never force push to main/master
+
+{{args}}

package/prompts/skills/coordinate.md

@@ -0,0 +1,21 @@
+---
+name: coordinate
+description: Break a complex task into subtasks and dispatch to multiple agents
+trigger: /coordinate
+---
+
+Use coordinator mode to tackle a complex task with multiple agents working in parallel.
+
+## How it works:
+1. **Plan**: A planning agent breaks your goal into independent subtasks
+2. **Dispatch**: Each subtask is assigned to a specialized sub-agent (explorer, implementer, test-writer, code-reviewer)
+3. **Execute**: Agents work in parallel waves (up to 3 concurrent)
+4. **Verify**: Optional verification agent checks the combined output
+5. **Report**: Summary of what each agent accomplished
+
+## Usage:
+Describe the complex task you want to coordinate. Be specific about the goal and any constraints.
+
+Example: "Refactor the auth module to use JWT tokens, update all tests, and review for security issues"
+
+{{args}}

package/prompts/skills/daily-review.md

@@ -0,0 +1,65 @@
+---
+name: daily-review
+description: Morning status check across projects, inbox, and blockers
+trigger: /daily-review
+---
+
+Morning routine to prepare for the day's work.
+
+## Steps
+
+1. **Show Inbox Status**
+   - Count notes in `00-Inbox/` with `status: captured`
+   - Highlight any with `urgency: now`
+   - Format: `Inbox: X items (Y urgent)`
+
+2. **Display Today's GSD Focus**
+   - Read each project's STATE.md current focus
+   - Show current phase, description, and progress for each active project
+   - Format as boxed sections per project with progress bars
+
+3. **List Active Blockers**
+   - Search for notes with `status: blocked` in all projects
+   - Show any GSD phases that are stuck
+   - Format: `Blockers: [Project] Feature X blocked by: ...`
+
+4. **Quick Actions**
+   Present options:
+   - Process inbox (`/process-inbox`)
+   - Continue GSD work (`/gsd:progress`)
+   - Plan today's tasks (manual)
+
+5. **Create Daily Note (Optional)**
+   - If user approves, create today's daily note in `01-Daily/`
+   - Use template from `01-Daily/_templates/daily-note.md`
+   - Pre-fill with GSD status and inbox count
+
+## Output Format
+
+```
+Daily Review - [Date]
+
+Inbox: X items (Y urgent)
+
+Focus
++-- Project A --------------------+
+| Phase: [phase name]             |
+| Progress: [progress bar] XX%   |
+| Current: [current task]        |
++---------------------------------+
++-- Project B --------------------+
+| Phase: [phase name]             |
+| Progress: [progress bar] XX%   |
+| Current: [current task]        |
++---------------------------------+
+
+Blockers: None
+
+What would you like to do?
+1. Process inbox
+2. Continue [Project A] work
+3. Continue [Project B] work
+4. Something else
+```
+
+{{args}}

package/prompts/skills/debug.md

@@ -0,0 +1,23 @@
+---
+name: debug
+description: Systematic debugging with error analysis
+trigger: /debug
+---
+
+Debug the issue described below using a systematic approach.
+
+Steps:
+1. **Reproduce**: Identify how to reproduce the issue
+2. **Locate**: Use Grep and Read to find the relevant code paths
+3. **Diagnose**: Trace the execution path, identify the root cause
+4. **Fix**: Make the minimal change that fixes the root cause
+5. **Verify**: Run the fix and confirm the issue is resolved
+6. **Prevent**: Check if similar issues exist elsewhere
+
+Rules:
+- Fix the root cause, not symptoms
+- Don't add workarounds unless the root cause is unfixable
+- Make the smallest change possible
+- Verify the fix doesn't break other functionality
+
+{{args}}

package/prompts/skills/deep-work.md

@@ -0,0 +1,129 @@
+---
+name: deep-work
+description: Strategic session kickoff with parallel exploration before acting
+trigger: /deep-work
+---
+
+You are starting a deep work session. Thoroughly investigate before acting. Follow these phases in order. Scale effort to task complexity.
+
+**User's task:** {{args}}
+
+---
+
+## Phase 0: Context Recovery (conditional)
+
+**Skip this phase if** you've already recovered context this session (e.g., via `/resume-branch`, `entire resume`, or earlier in the conversation). Don't duplicate work.
+
+If context has NOT been recovered yet:
+
+1. Read project memory files -- search for entries relevant to this task
+2. Check git state: run `git status` and `git log --oneline -10`
+3. If on a non-main branch, run `entire resume <branch>` for session context
+4. Scan the project's configuration for conventions relevant to this task
+
+Output a brief **Current State** summary (3-5 lines): branch, recent changes, relevant memory entries. If skipping, state "Context already recovered" and move on.
+
+---
+
+## Phase 1: Task Classification (immediate, no agents)
+
+Analyze the user's task and classify it:
+
+**Type:** feature | bug | refactor | investigation | optimization | architecture
+**Scope:** surgical (1-2 files) | focused (3-10 files) | broad (10+ files) | architectural (system-wide)
+**Familiarity:** known territory | partially known | unexplored
+
+Map to exploration depth:
+
+| Scope | Agents to Deploy | Delivery Mode |
+|-------|-----------------|---------------|
+| surgical | 1 (patterns) | Brief + draft plan + questions together |
+| focused | 2 (patterns + impact) | Brief + draft plan + questions together |
+| broad | 3 (patterns + impact + risk) | Brief + questions first, then plan after answers |
+| architectural | 3+ (full spectrum) | Brief + questions first, then plan after answers |
+
+State your classification and depth explicitly before proceeding.
+
+---
+
+## Phase 2: Parallel Exploration (adaptive agent deployment)
+
+Deploy agents **in parallel** based on depth from Phase 1. The **Patterns & Conventions** agent is the most critical -- give it the heaviest workload. Other agents should be targeted, not broad.
+
+### Agent Missions
+
+| Agent | Mission | Deploy When |
+|-------|---------|-------------|
+| **Patterns & Conventions** (primary) | How does the codebase handle similar things? What utilities/patterns exist to reuse? What conventions must be followed? Search for analogous implementations. Find the specific files, functions, and patterns that this task should mirror. | Always -- this is the workhorse agent |
+| **Impact & Dependencies** | What specifically will this change touch? What imports/calls the affected code? What tests cover it? Map the concrete dependency graph -- files and functions, not abstractions. | Focused+ |
+| **Risk & Edge Cases** | Specific security implications for THIS change? Concrete performance concerns? Actual error scenarios based on the code paths involved? Skip generic risk lists. | Broad+ |
+| **Architecture & Design** | Design options with concrete tradeoffs specific to this codebase. How does this fit the existing system architecture? What precedents exist for similar decisions? | Architectural only |
+| **Prior Art & History** | Has this been attempted before? Check git log for related commits, memory files for past decisions, session transcripts for context. | Architectural or unfamiliar territory only |
+
+Each agent must report: **findings**, **relevant file paths with line numbers**, **reusable utilities**, and **risks/unknowns**.
+
+Deploy all applicable agents in a **single message** (parallel execution).
+
+---
+
+## Phase 3: Synthesis Brief
+
+After all agents complete, combine findings into this structure:
+
+```
+## Situation
+[Current state of the relevant code/subsystem -- 2-4 sentences]
+
+## Approach
+[What needs to change and the recommended path -- be specific about strategy]
+
+## Key Findings
+- [Patterns/conventions to follow -- with file paths]
+- [Existing utilities to reuse -- with file:line references]
+- [Dependencies and impact areas]
+
+## Risks & Unknowns
+- [Risk 1 -- proposed mitigation]
+- [Unknown 1 -- needs user input]
+```
+
+Keep it concise. No filler. Every bullet should be actionable or inform a decision.
+
+---
+
+## Phase 4: Questions + Plan (merged for speed)
+
+**For surgical/focused scope:** Present the synthesis brief, a draft execution plan, AND strategic questions in a single response. Frame questions as: "Here's what I'd do -- but these decisions could change the approach:"
+
+**For broad/architectural scope:** Present the synthesis brief and strategic questions first. Wait for answers before producing the plan, since the answers materially change the approach.
+
+### Question Quality Rules
+
+Questions must be:
+- **Specific** -- emerged from actual exploration, not generic
+- **Decision-forcing** -- present concrete options with tradeoffs discovered in Phase 2
+- **Minimal** -- only ask what you genuinely can't decide autonomously
+
+Good: "The auth middleware uses session-based auth but this endpoint needs API key support. Should we extend the existing middleware or create a separate auth path?"
+Bad: "What authentication approach do you prefer?"
+
+### Execution Plan Structure
+
+1. **Files to create/modify** -- specific paths, what changes in each
+2. **Sequence** -- ordered by dependencies (what must happen first)
+3. **Reuse** -- existing code/utilities to leverage (with file:line references)
+4. **Verification** -- how to test end-to-end (specific commands, browser checks, etc.)
+
+After the user responds (answers questions and/or approves plan), begin implementation directly.
+
+---
+
+## Key Principles
+
+- **Adaptive depth** -- a 1-file bug fix gets 1 agent and ships fast; a system redesign gets full investigation. Never over-investigate simple tasks.
+- **Patterns agent is king** -- for convention-heavy codebases, the patterns agent does the most valuable work. Other agents should be targeted, not broad. Don't deploy agents that will return generic findings.
+- **Reuse-first** -- agents specifically look for existing patterns and utilities. Don't reinvent.
+- **Memory-aware** -- check past session context before exploring from scratch. Don't duplicate `/resume-branch` work.
+- **Speed over ceremony** -- for surgical/focused tasks, merge the brief + plan + questions into one response. Don't create blocking pauses between phases.
+- **Strategic questions over volume** -- ask the RIGHT questions, not many questions.
+- **Show your work** -- output the classification, agent findings summary, and brief so the user sees the thinking.

package/prompts/skills/explore.md

@@ -0,0 +1,24 @@
+---
+name: explore
+description: Deep codebase exploration and architecture analysis
+trigger: /explore
+---
+
+Thoroughly explore this codebase and provide a comprehensive analysis.
+
+Steps:
+1. Use Glob to map the directory structure
+2. Read key files: package.json, README, config files, entry points
+3. Use Grep to find patterns: exports, classes, routes, handlers
+4. Identify the architecture: framework, patterns, layers
+5. Map dependencies between modules
+
+Report:
+- Project type and framework
+- Directory structure overview
+- Key entry points and modules
+- Architecture patterns used
+- Notable dependencies
+- Areas of complexity or tech debt
+
+{{args}}

package/prompts/skills/init.md

@@ -0,0 +1,39 @@
+---
+name: init
+description: Initialize AshlrCode for a new project (create ASHLR.md)
+trigger: /init
+---
+
+Initialize AshlrCode for this project by creating an ASHLR.md file with project-specific instructions.
+
+Steps:
+1. Use Glob and LS to understand the project structure
+2. Read package.json, Cargo.toml, requirements.txt, or equivalent for project type
+3. Read README.md if it exists
+4. Identify: framework, language, test commands, build commands, conventions
+5. Create ASHLR.md with:
+
+```markdown
+# Project Name
+
+Brief description of what this project is.
+
+## Architecture
+- Framework and key libraries
+- Directory structure overview
+- Key entry points
+
+## Commands
+- How to build: `command`
+- How to test: `command`
+- How to run: `command`
+
+## Conventions
+- Coding style notes
+- Naming conventions
+- File organization patterns
+```
+
+Keep it concise — only include what would help an AI assistant work effectively on this project.
+
+{{args}}

package/prompts/skills/kairos.md

@@ -0,0 +1,19 @@
+---
+name: kairos
+description: Start autonomous KAIROS mode with terminal focus-aware behavior
+trigger: /kairos
+---
+
+Activate KAIROS — autonomous agent mode. The agent will:
+
+- **Detect terminal focus** to adjust autonomy level:
+  - Focused (you're watching): Collaborative, asks before big changes
+  - Unfocused (you're away): Full auto, commits and pushes independently
+  - Unknown: Balanced default
+- **Heartbeat loop**: Keeps working between your inputs (every 30s)
+- **Push notifications**: macOS notification when done or on error
+- **Auto-stop**: Stops when nothing is left to do or you say stop
+
+Give KAIROS a goal to work on autonomously:
+
+{{args}}

package/prompts/skills/plan.md

@@ -0,0 +1,19 @@
+---
+name: plan
+description: Enter plan mode for structured exploration and planning
+trigger: /plan-task
+---
+
+I need you to enter plan mode and create a detailed implementation plan before making any changes.
+
+Steps:
+1. Call EnterPlan to activate plan mode
+2. Use Read, Glob, and Grep to explore the relevant code
+3. Ask me strategic questions using AskUser if you need direction
+4. Write a detailed plan using PlanWrite that includes:
+   - Context: what problem this solves
+   - Approach: what files to modify and how
+   - Verification: how to test the changes
+5. Call ExitPlan when the plan is ready for my review
+
+{{args}}