🐰 Bunnies Code

A multi-surface, multi-topology, tool-driven agent runtime platform. Rather than being a simple terminal app, it serves as a full-featured capability orchestration platform with the TUI (Terminal UI) as just one of many user-facing surfaces.

Key Surfaces

| Surface | Description | |---------|-------------| | Interactive CLI/TUI | Default REPL workflow powered by React/Ink | | Headless / Print | Non-interactive structured output for SDK and automation | | SDK / Structured I/O | Control protocol channels for programmatic access | | Bridge / Remote Control | Use the local machine as a remote-control environment | | Remote Session Viewer | Connect to and observe remote running sessions | | Direct-Connect Server | Drive sessions via WebSocket / HTTP | | SSH Remote | Initiate remote runs from the local machine | | Background / Daemon | Long-running sessions with attach/logs/kill | | MCP Server/Client | External tool and resource integration via Model Context Protocol | | Plugins / Skills / Agents | User, project, and plugin-level extensibility |

Tech Stack

• Runtime: Bun (≥ 1.3.0) / Node.js (≥ 18.0.0)
• Language: TypeScript / TSX
• UI Framework: React + Ink (custom runtime/renderer)
• Protocol: Model Context Protocol (MCP)
• Schema Validation: Zod

Project Structure

bunnies-code/
├── assets/              # Sprite assets (standard & compact)
├── docs/
│   ├── ai-harness/      # Architecture, module index, engineering rules, playbooks
│   ├── plans/           # Technical and execution plans
│   └── requirements/    # Feature requirements (PRDs, QA checklists)
├── scripts/
│   ├── build-local.mjs  # Local build script (Bun bundler)
│   ├── sync-vendor.mjs  # Sync vendor assets from upstream npm package
│   └── generate-sprite-data.ts
├── src/
│   ├── entrypoints/     # CLI entry point & fast-path mode dispatch
│   ├── main.tsx         # Application composition root
│   ├── cli/             # Non-interactive commands & print surface
│   ├── screens/         # Screen-level components (REPL, Doctor, Resume)
│   ├── components/      # Reusable UI component library (100+ components)
│   ├── hooks/           # React hooks library (80+ hooks)
│   ├── ink/             # Custom Ink runtime, renderer, layout engine
│   ├── QueryEngine.ts   # Query lifecycle & session state ownership
│   ├── query.ts         # Agent loop state machine
│   ├── tools/           # Tool registry & implementations (40+ tools)
│   ├── tasks/           # Task model (LocalAgent, InProcess, Remote, etc.)
│   ├── skills/          # Skill loading & execution
│   ├── plugins/         # Plugin system (built-in & bundled)
│   ├── services/        # Shared services (API, MCP, compact, analytics)
│   ├── state/           # Session state management (AppStateStore)
│   ├── bridge/          # Bridge / remote-control logic
│   ├── remote/          # Remote session management
│   ├── server/          # Direct-connect server
│   ├── keybindings/     # Key binding system
│   ├── vim/             # Vim mode (motions, operators, text objects)
│   ├── voice/           # Voice interaction
│   ├── buddy/           # Companion / sprite system
│   ├── utils/           # Shared utilities (200+ modules)
│   ├── types/           # TypeScript type definitions
│   ├── constants/       # Constants
│   ├── context/         # React context providers
│   ├── bootstrap/       # Startup initialization
│   ├── migrations/      # Data migrations (12 scripts)
│   └── native-ts/       # Native TS modules (color-diff, file-index, yoga-layout)
├── stubs/               # Local package stubs for internal dependencies
├── package.json
└── tsconfig.json

Architecture

The system follows a layered architecture:

| Layer | Name | Responsibility | |-------|------|----------------| | L0 | Entrypoints & Mode Selection | CLI parsing, mode dispatch, fast-path routing | | L1 | Session Orchestration | Session assembly, state wiring, I/O, recovery | | L2 | Agent Core | Model interaction, query loop, context management, tool orchestration | | L3 | Capability Plane | Tools, tasks, MCP, skills, plugins, output styles | | L4 | Experience / Surface | TUI, Ink runtime, components, keybindings, vim, voice, buddy | | L5 | Platform / Foundation | Utilities, services, config, types, migrations |

For full architecture details, see docs/ai-harness/ARCHITECTURE.md.

Getting Started

Prerequisites

• Bun ≥ 1.3.0
• Node.js ≥ 18.0.0

Quick Setup

# One-command setup: install dependencies and build a local development bundle
npm run setup:local

This runs the following steps:

1. bun install — Install all dependencies
2. node scripts/build-local.mjs — Bundle the CLI with Bun, stage bundled runtime assets, and prepare dist/

Manual Setup

# 1. Install dependencies
bun install

# 2. Build the CLI bundle
node scripts/build-local.mjs

Public Release Build

# Build the publishable npm artifact
npm run build:release

# Inspect the npm tarball contents
npm pack --dry-run --json

# Create the tarball
npm pack

Install and Upgrade

# Install globally from npm
npm install -g bunnies-code

# Launch
bunnies

# Upgrade later
npm install -g bunnies-code@latest

Start With A Specific TUI Pack

Use --tui-pack to select a theme bundle at startup.

If the pack is already installed or otherwise loadable by name:

node dist/cli.js --tui-pack newjeans-pack

If you want to launch directly from a local plugin directory and make sure all pack-scoped content is loaded for this session:

node dist/cli.js --tui-pack ./examples/newjeans-pack --agent intent-guardian-infp

Smoke Tests

# Verify the build outputs a version
node dist/cli.js --version

# Verify help output
node dist/cli.js --help

# Verify packaged companion fallback with an empty config directory
CLAUDE_CONFIG_DIR=$(mktemp -d) node dist/cli.js plugin preview --slot bottom-companion --state idle

Available Scripts

| Script | Command | Description | |--------|---------|-------------| | build | npm run build | Bundle the CLI into dist/cli.js | | build:release | npm run build:release | Build the publishable npm artifact | | pack:release | npm run pack:release | Build release output and create the npm tarball | | sync:vendor | npm run sync:vendor | Sync vendor assets from upstream package | | setup:local | npm run setup:local | Full local setup (install + sync + build) | | smoke:version | npm run smoke:version | Smoke test: print version | | smoke:help | npm run smoke:help | Smoke test: print help |

AI-Assisted Development

This project includes structured guidance for AI-assisted development workflows:

• AGENTS.md — Working rules, task routing, and output requirements for AI agents
• docs/ai-harness/ — Comprehensive documentation including:
  • INDEX.md — Documentation entry point
  • ARCHITECTURE.md — System architecture map
  • MODULE_INDEX.md — Complete module registry
  • ENGINEERING_RULES.md — Engineering standards and conventions
  • COMMANDS.md — Available commands reference
  • REVIEW_CHECKLIST.md — Code review checklist
  • TESTING_PLAYBOOK.md — Testing guidelines
  • TRIAGE_PLAYBOOK.md — Bug triage procedures

Key Concepts

| Term | Definition | |------|------------| | Surface | A user interaction surface (REPL, print, remote viewer, etc.) | | Agent Core | Model interaction, query loop, and tool orchestration core | | Tool | Core capability contract for the agent runtime (file R/W, shell, web, MCP, etc.) | | Task | Long-running or async execution unit (local_bash, local_agent, remote_agent, etc.) | | Skill | Workflow & knowledge executable packaged as markdown/frontmatter | | Plugin | Installable extension supporting commands, agents, skills, hooks, and output styles | | MCP | Model Context Protocol — external tool and resource integration | | Output Style | Model output style configuration (not a TUI theme) |

Distribution Notes

The npm package is published as bunnies-code and installs the bunnies command. This repository remains marked UNLICENSED unless separate distribution terms are provided.