beads

BeadsLog

Agent-first codebase memory.

BeadsLog remembers what your project actually became — the decisions, the dead ends, which components depend on which — recorded as you and your agent work and stored as a searchable graph in git.

That memory pays off twice. Agents reload full context in seconds — the architecture, the past decisions, why the last change was made — so you stop re-explaining your project every session. And it catches drift: BeadsLog records what you and your agent actually decided, so when an agent writes thousands of lines a session, the places the code wandered from the plan stay visible instead of compounding.

Built on Beads, a git-native issue tracker for AI agents.

For you if:

• You vibecode on a team at high pace. Everyone's agents share one memory and build on each other's work instead of colliding or redoing it.
• You're a solo vibecoder juggling many projects. Pick one back up after weeks; your agent reloads the context in seconds.
• You don't have the dev reflexes yet — git hygiene, writing down scope and architecture, coordinating work across people. BeadsLog handles that.
• You re-explain your project to your agent every session.

Not for you if: you're a seasoned dev who codes without AI agents.

Built for vibecoders, agent-agnostic — works with Claude Code, Cursor, Codex, ….

Quick Start

Requires Go 1.24+.

go install github.com/untoldecay/BeadsLog/cmd/bd@latest
bd init        # set up in this project — private by default, nothing is shared unless you choose to
bd onboard     # ask your agent to run this; it reads the setup and connects itself

[!TIP] BeadsLog keeps its notes on a separate git branch, not mixed into the code you and your team work on. Working solo, or on a team that doesn't use BeadsLog? Running Modes shows the fully private setup.

What agents do with it

As your agent works, it writes a short devlog — plain markdown, a few sentences. You don't write these; the agent does:

Switched auth to webhook-first validation — the sync response timed out under load. Touches AuthService, StripeClient.

Weeks later, any agent reads that back before touching the code — no re-explaining, no grep-and-guess. Your agent runs these, not you (local and instant — no network, no waiting):

Trust badges keep the history honest: [🟢 VALIDATED] code landed in main; [⏸ PAUSED] and [🚫 ABANDONED] warn agents off dead branches. See Lifecycle.

The loop — acquire context, implement, record — runs as your agent works. The one command you run yourself: bd catchup.

Does it hold up?

Blind-judged against brute-force grep, BeadsLog wins even on flat lookups — ~50% fewer tool-calls at equal answer quality — and the gap widens with complexity: on system-reasoning questions, ~14% higher quality for ~15% fewer tokens. See the benchmarks for the method and every run.

Docs

Start here

• Running Modes — team, solo, switching: which to run and why.
• Commands — full command reference.
• Use Cases — real scenarios for agents and teams.

Concepts

• Devlog — the "Bead" and the narrative format.
• Lifecycle States — active, paused, abandoned, validated.
• Devlog Architecture — how the graph is built.
• Benchmarks — BeadsLog vs grep, blind-judged; run your own with bd bench.

Operate

• Catchup · Hooks · Ollama Enrichment
• Issue Architecture · Installation