Why Acolyte?
Acolyte is an open-source AI coding agent that remembers you and your projects, with observable execution, provider choice, and developer control.
Why open source?
Claude Code and Codex are excellent products. If you’re happy with a single provider’s CLI and don’t need to customize agent behavior, they’re the easiest path.
Open-source agents like Acolyte exist for the cases where that’s not enough:
- provider choice — use OpenAI, Anthropic, Google, or any OpenAI-compatible endpoint — switch models per task without switching tools
- self-hosted — run everything on your own infrastructure with no data leaving your network
- customizable agent behavior — lifecycle phases, effects, and memory strategies are all configurable — not locked behind a closed product surface
- transparent execution — every tool call and effect decision is observable in structured logs — no black box
- no vendor lock-in — your sessions, memory, and configuration are local files you own
Acolyte is for developers who want reliable, observable agent behavior, not a black box. To run it from source, see Local development.
What makes Acolyte different
| Feature | What Acolyte does |
|---|---|
| Memory | Durable facts about you and your projects, distilled from completed work and scoped to session, project, or user |
| Architecture | Headless daemon with typed RPC — CLI, editors, and custom clients share the same protocol |
| Lifecycle | 4-phase pipeline (resolve → prepare → generate → finalize) in separate, testable modules |
| Post-write effects | Automatic format and lint after writes; lint errors surface for the model to decide on |
| Context budgeting | Proactive token budgeting via tiktoken with system prompt reservation and priority-based allocation |
| Developer experience | Custom React TUI with fuzzy search, autocomplete, model picker, structured output, and AST-based editing |
Memory
Acolyte learns you and your projects from the work itself: a rule stated once is kept as a durable fact and recalled in a later session when the model judges it relevant. Instead of compressing context under pressure, it proactively extracts durable observations from completed work and commits them at session, project, or user scope. A later observation can supersede the records it replaces, which move to a restorable archive with lineage. The pipeline is explicit and each stage is strategy-injectable.
Daemon architecture
The server runs headless. CLI, editor plugins, and third-party clients all connect over the same typed RPC protocol. The TUI is just another client with no special access. Multiple clients can share a session, and integrations speak the protocol instead of forking the project.
Lifecycle pipeline
Every request flows through four explicit phases, each in its own module with its own tests. The lifecycle trusts the model to make good decisions within a single generation pass. Format and lint effects run automatically after writes, and lint errors surface for the model to decide on. A step budget and token ceiling inlined into tool execution prevent runaway loops, and tool results are truncated at the serialization boundary to bound context growth.
Context budgeting
The system prompt is measured and reserved before history allocation begins. Remaining budget is filled by priority: pinned context → file attachments → history → tool payloads. Older tool outputs are progressively capped. When output is truncated, the model sees an explicit notice, not silent data loss.
Developer experience
The CLI ships a custom React-based TUI: fuzzy search and autocomplete with suggestion and correction for file paths, sessions, commands, and skills. A model picker queries provider APIs for available models. Tool output is structured with typed rendering. AST-based editing and scanning run through ast-grep.
Next steps
- Architecture — How the system is built.
- Comparison — How Acolyte compares to other open-source agents.
- Benchmarks — Measured code quality metrics.