A coding agent you can inspect.
Acolyte is an open-source, terminal-first AI coding agent with an opinionated runtime and explicit extension seams. Its single-pass lifecycle, on-demand memory, and transparent execution make decisions visible and boundaries explicit.
curl -fsSL https://acolyte.sh/install | shInstalls the latest released binary for macOS and Linux. It keeps itself up to date automatically — see Updates. To run from source instead, see Local development.
Requires Git 2.14 or newer on PATH: Acolyte reports every file edit as a Git diff, and /workspaces manages Git worktrees.
CLI → typed RPC → task queue → lifecycle → model + tools
- Daemon: A persistent server with typed RPC for the CLI, editors, and custom clients.
- Lifecycle: Explicit, testable phases, effects, and completion rules.
- Memory: Durable session, project, and user context retrieved on demand.
- Workspace: Detected project commands and a validated boundary for tool access.
- Context: Planned input budgets, bounded tool payloads, and visible token use.
- Trace: Local task timelines and structured logs for runtime inspection.
The codebase is TypeScript on Bun, with Zod validation at runtime boundaries and direct dependency injection rather than a container. Read Architecture for the component model and Lifecycle for request execution.
Requires Bun and Git 2.14 or newer.
git clone https://github.com/cniska/acolyte.git
cd acolyte
bun install
bun run devbun run dev starts a watch-mode daemon and opens the CLI client. It restarts any local daemon already using the development port, then stops the daemon it started when the client exits.
For daily dogfooding, link the checkout CLI into your PATH:
mkdir -p ~/.local/bin
ln -sf "$PWD/src/cli.ts" ~/.local/bin/acolyteUse scripts/install.sh only when you want the latest released binary instead of the local source checkout.
Provider credentials are not needed to run the test suites. To use the agent against a provider while developing, configure one once for your user account:
bun run src/cli.ts auth vercel --keyThis stores the key in Acolyte's private global credentials file. Use openai, anthropic, or google instead to configure a direct provider. See Configuration for credential precedence, local models, and provider settings.
| Command | Purpose |
|---|---|
bun run dev |
Start the watch-mode daemon and interactive CLI. |
bun run dogfood |
Run the local CLI with debug logging against the current source. |
bun run run "<prompt>" |
Run a one-shot task from the current source. |
bun run serve |
Start only the daemon. |
bun run format |
Format the repository with Biome. |
bun run verify |
Run linting, type checking, all tests, and the dependency audit. |
Run focused suites while iterating:
bun test
bun run test:unit
bun run test:int
bun run test:tui
bun run test:perfbun test runs every test. bun run verify is the required full validation before a pull request. See Testing for test boundaries, naming, and coverage.
| Path | Purpose |
|---|---|
src/ |
CLI, daemon, lifecycle, tools, memory, protocol, and terminal UI. |
docs/ |
Canonical product, runtime, and development documentation. |
scripts/ |
Development, release, test, benchmark, and behavior-harness scripts. |
.githooks/ |
Hooks installed by bun install. |
See src/README.md for source-module naming, entry points, test suffixes, and subsystem directories.
Read AGENTS.md before changing an unfamiliar subsystem. It defines architectural extension points, invariants, and test boundaries.
Contributions are welcome. See CONTRIBUTING.md and AGENTS.md.
MIT © Christoffer Niska