ashlrcode 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AshlrAI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,295 @@
+# AshlrCode (ac)
+
+**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)]()
+[![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**
+
+---
+
+## 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.
+
+---
+
+## Quick Start
+
+```bash
+git clone https://github.com/ashlrai/ashlrcode.git
+cd ashlrcode
+bun install
+bun link                    # makes 'ac' available globally
+
+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
+```
+
+---
+
+## 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
+
+### Tools (42)
+
+| 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 (34)
+
+| 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 <question>` | Side question in sub-agent (no main context pollution) |
+| `/autopilot` | Autonomous scan / queue / approve / run / auto |
+| `/kairos <goal>` | 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 input box, context bar, and autocomplete
+- **Buddy system** — persistent ASCII pet companion with species, moods, hats, rarity, and stats
+- **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
+
+### 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 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
+
+---
+
+## 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:
+
+```json
+{
+  "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-1-fast-reasoning | $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
+
+```bash
+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
+
+```bash
+git clone https://github.com/ashlrai/ashlrcode.git
+cd ashlrcode
+bun install
+
+bun run dev                 # watch mode
+bun run start               # run CLI
+bun test                    # 335 tests, 666 assertions, ~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/                  # 42 tools (32 files)
+├── skills/                 # Skill loader + registry
+├── mcp/                    # MCP client, manager, OAuth
+├── 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

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "ashlrcode",
+  "version": "1.0.0",
+  "description": "Multi-provider AI coding agent CLI — 42 tools, 34 commands, autonomous mode",
+  "module": "src/cli.ts",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ashlrai/ashlrcode"
+  },
+  "keywords": ["ai", "coding", "agent", "cli", "xai", "grok", "claude", "multi-provider", "autonomous"],
+  "files": ["src/", "README.md", "LICENSE"],
+  "bin": {
+    "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"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.14"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.82.0",
+    "chalk": "^5.6.2",
+    "fast-glob": "^3.3.3",
+    "ink": "^6.8.0",
+    "ink-text-input": "^6.0.0",
+    "openai": "^6.33.0",
+    "react": "^19.2.4",
+    "react-devtools-core": "^7.0.1"
+  },
+  "optionalDependencies": {
+    "puppeteer": "^24.0.0"
+  }
+}

package/src/__tests__/branded-types.test.ts

@@ -0,0 +1,47 @@
+import { test, expect, describe } from "bun:test";
+import {
+  asSystemPrompt,
+  asSessionId,
+  asAgentId,
+  asToolName,
+} from "../types/branded.ts";
+
+describe("Branded Types", () => {
+  test("asSystemPrompt returns the string", () => {
+    const result = asSystemPrompt("You are a helpful assistant.");
+    expect(result).toBe("You are a helpful assistant.");
+    expect(typeof result).toBe("string");
+  });
+
+  test("asSessionId returns the string", () => {
+    const result = asSessionId("sess-abc-123");
+    expect(result).toBe("sess-abc-123");
+    expect(typeof result).toBe("string");
+  });
+
+  test("asAgentId returns the string", () => {
+    const result = asAgentId("agent-007");
+    expect(result).toBe("agent-007");
+    expect(typeof result).toBe("string");
+  });
+
+  test("asToolName returns the string", () => {
+    const result = asToolName("Bash");
+    expect(result).toBe("Bash");
+    expect(typeof result).toBe("string");
+  });
+
+  test("all branded type functions exist and are callable", () => {
+    expect(typeof asSystemPrompt).toBe("function");
+    expect(typeof asSessionId).toBe("function");
+    expect(typeof asAgentId).toBe("function");
+    expect(typeof asToolName).toBe("function");
+  });
+
+  test("branded values work with string operations", () => {
+    const prompt = asSystemPrompt("hello world");
+    expect(prompt.toUpperCase()).toBe("HELLO WORLD");
+    expect(prompt.length).toBe(11);
+    expect(prompt.includes("world")).toBe(true);
+  });
+});

package/src/__tests__/context.test.ts

@@ -0,0 +1,163 @@
+import { test, expect, describe } from "bun:test";
+import { estimateTokens, needsCompaction, snipCompact } from "../agent/context.ts";
+import type { Message } from "../providers/types.ts";
+
+describe("estimateTokens", () => {
+  test("estimates tokens for string content", () => {
+    const messages: Message[] = [
+      { role: "user", content: "Hello world" }, // 11 chars => ceil(11/4) = 3
+    ];
+    expect(estimateTokens(messages)).toBe(3);
+  });
+
+  test("returns 0 for empty messages", () => {
+    expect(estimateTokens([])).toBe(0);
+  });
+
+  test("estimates tokens for text blocks", () => {
+    const messages: Message[] = [
+      {
+        role: "assistant",
+        content: [{ type: "text", text: "abcdefgh" }], // 8 chars => 2 tokens
+      },
+    ];
+    expect(estimateTokens(messages)).toBe(2);
+  });
+
+  test("estimates tokens for tool_use blocks", () => {
+    const messages: Message[] = [
+      {
+        role: "assistant",
+        content: [
+          { type: "tool_use", id: "1", name: "Bash", input: { command: "ls" } },
+        ],
+      },
+    ];
+    // name "Bash" (4) + JSON.stringify({command: "ls"}) (16) = 20 => ceil(20/4) = 5
+    const tokens = estimateTokens(messages);
+    expect(tokens).toBeGreaterThan(0);
+  });
+
+  test("estimates tokens for tool_result blocks", () => {
+    const messages: Message[] = [
+      {
+        role: "tool",
+        content: [
+          { type: "tool_result", tool_use_id: "1", content: "file1.ts\nfile2.ts" },
+        ],
+      },
+    ];
+    const tokens = estimateTokens(messages);
+    expect(tokens).toBeGreaterThan(0);
+  });
+
+  test("sums across multiple messages", () => {
+    const messages: Message[] = [
+      { role: "user", content: "aaaa" }, // 4 chars => 1 token
+      { role: "assistant", content: "bbbbbbbb" }, // 8 chars => 2 tokens
+    ];
+    expect(estimateTokens(messages)).toBe(3);
+  });
+});
+
+describe("needsCompaction", () => {
+  test("returns false when well under limit", () => {
+    const messages: Message[] = [{ role: "user", content: "hi" }];
+    expect(needsCompaction(messages, 100)).toBe(false);
+  });
+
+  test("returns true when over limit", () => {
+    // Create a message that's clearly over the default limit
+    // Default: maxContextTokens=100000, reserveTokens=8192
+    // So threshold is 91808 tokens => 91808 * 4 = 367232 chars
+    const bigContent = "x".repeat(400_000);
+    const messages: Message[] = [{ role: "user", content: bigContent }];
+    expect(needsCompaction(messages, 0)).toBe(true);
+  });
+
+  test("respects custom config", () => {
+    // "hello world test" = 16 chars / 4 = 4 tokens. Limit 3, so should trigger.
+    const messages: Message[] = [{ role: "user", content: "hello world test" }];
+    expect(
+      needsCompaction(messages, 0, { maxContextTokens: 3, reserveTokens: 0 })
+    ).toBe(true);
+  });
+
+  test("accounts for system prompt tokens", () => {
+    const messages: Message[] = [{ role: "user", content: "hi" }];
+    // "hi" = 1 token. systemPromptTokens = 95000. Total = 95001.
+    // maxContext 100000 - reserve 8192 = 91808. 95001 > 91808 = true
+    expect(
+      needsCompaction(messages, 95_000, {
+        maxContextTokens: 100_000,
+        reserveTokens: 8192,
+      })
+    ).toBe(true);
+  });
+});
+
+describe("snipCompact", () => {
+  test("does not modify short tool results", () => {
+    const messages: Message[] = [
+      {
+        role: "tool",
+        content: [
+          { type: "tool_result", tool_use_id: "1", content: "short result" },
+        ],
+      },
+    ];
+    const result = snipCompact(messages);
+    expect((result[0]!.content as any)[0].content).toBe("short result");
+  });
+
+  test("truncates tool results longer than 2000 chars", () => {
+    const longContent = "a".repeat(3000);
+    const messages: Message[] = [
+      {
+        role: "tool",
+        content: [
+          { type: "tool_result", tool_use_id: "1", content: longContent },
+        ],
+      },
+    ];
+    const result = snipCompact(messages);
+    const content = (result[0]!.content as any)[0].content as string;
+    expect(content.length).toBeLessThan(longContent.length);
+    expect(content).toContain("[... truncated ...]");
+  });
+
+  test("preserves string content messages unchanged", () => {
+    const messages: Message[] = [{ role: "user", content: "hello" }];
+    const result = snipCompact(messages);
+    expect(result[0]!.content).toBe("hello");
+  });
+
+  test("preserves text blocks unchanged", () => {
+    const messages: Message[] = [
+      {
+        role: "assistant",
+        content: [{ type: "text", text: "some analysis" }],
+      },
+    ];
+    const result = snipCompact(messages);
+    expect((result[0]!.content as any)[0].text).toBe("some analysis");
+  });
+
+  test("truncated result keeps first 800 and last 800 chars", () => {
+    const longContent = "a".repeat(800) + "MIDDLE" + "b".repeat(800) + "c".repeat(1400);
+    const messages: Message[] = [
+      {
+        role: "tool",
+        content: [
+          { type: "tool_result", tool_use_id: "1", content: longContent },
+        ],
+      },
+    ];
+    const result = snipCompact(messages);
+    const content = (result[0]!.content as any)[0].content as string;
+    // Should start with 800 chars from the beginning
+    expect(content.startsWith("a".repeat(800))).toBe(true);
+    // Should end with last 800 chars from the original
+    expect(content.endsWith(longContent.slice(-800))).toBe(true);
+  });
+});