When robots forget

Imagine hiring a brilliant programmer. They solve complex problems, write clean code, understand your architecture. But they have one tiny flaw: every few hours, their memory gets wiped. They start from scratch. They don't remember what they were working on, what you decided together, or why the code is structured the way it is.

That's exactly what happens with Claude Code and other AI agents.

When context fills up (and it fills up fast if you're working on a real project), the system performs "compaction." It summarizes the conversation and throws away everything else. The problem is that summary loses nuance, decisions, and most importantly, the state of ongoing tasks.

The solution? Two tools that complement each other: Linear for you and Beads for your AI.

Linear: Your product view

Linear is a modern issue tracker. If you've used Jira, imagine the opposite: fast, clean, and doesn't make you want to gouge your eyes out.

What I use it for

• Product backlog: Features, bugs, epics. Everything that needs doing at the business level
• Roadmap: What goes first, what comes after
• Communication: The rest of the team (if there is one) can see status

Real example

QIN-500: Add dark mode to application
QIN-501: Optimize image loading
QIN-502: Integrate payment gateway

These are product tasks. They're the "what needs to be done." They don't say anything about how to do it. That's the developer's job... or your AI agent's.

Beads: Your AI's memory

This is where Beads comes in, created by Steve Yegge (the same guy behind those famous Google and Amazon rants).

Beads is an issue tracker that lives inside your repository. But it's not for you, it's for your AI agent. It's their persistent memory.

The problem it solves

When I work with Claude Code on a complex task, things like this happen:

1. I read issue QIN-500 from Linear
2. I investigate the current architecture
3. I create a mental plan of 5 steps
4. I start implementing...
5. 💥 COMPACTION 💥
6. "Hello, I'm Claude. How can I help you?"

All the context, the plan, the progress... evaporated. It's like the movie Memento, but less cinematic and more frustrating.

The solution

With Beads, before compacting, state gets persisted in .beads/ inside the repo:

bd create --title "Research current theme system" --priority P2
bd create --title "Create ThemeContext" --priority P2
bd create --title "Add toggle in Settings" --priority P2

After compaction, the first thing I do is:

bd ready

And boom: I know exactly where I was.

📋 Ready work (2 issues with no blockers):

1. [P2] acme-a3f2: Create ThemeContext
2. [P2] acme-b4c5: Add toggle in Settings

How it works

Beads saves everything in your repo:

your-project/
└── .beads/
    ├── beads.db       # SQLite database
    ├── issues.jsonl   # Issues in versionable format
    └── config.yaml    # Configuration

Since it's in git, it versions with your code. You can see history, branch, merge... It's code, not an external service.

The coexistence: Linear + Beads

The trick is: they don't compete, they complement each other.

The flow in practice

YOU (in Linear):
  QIN-500: Add dark mode

CLAUDE (in Beads, during session):
  acme-a1b2: Research theme system [DONE]
  acme-c3d4: Create ThemeContext [IN PROGRESS]
  acme-e5f6: Add toggle in Settings [BLOCKED by c3d4]
  acme-g7h8: Tests for dark mode [BLOCKED by e5f6]

COMMIT (when finished):
  feat(web): add dark mode toggle (QIN-500)

Linear has the what. Beads has the how.

Quick installation

Beads

Important: the bd CLI is installed once on your system. But .beads/ is initialized per project. It's like git: you install git once, but you do git init in each repo.

# 1. Install CLI (once, globally)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# 2. Add to PATH (if it didn't do it automatically)
# In fish:
fish_add_path ~/.local/bin
# In bash/zsh:
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc

# 3. Configure Claude Code integration (once)
bd setup claude

# 4. Initialize in EACH project where you want to use it
cd your-project
bd init

After bd init, you'll see a .beads/ directory in your project. Decide: do you commit it to the repo (shared with the team) or add it to .gitignore (private memory for your AI)?

I commit it. That way if someone else works with Claude on the same repo, they have the context.

Linear

Linear is a web service. Create an account at linear.app and you're set. If you use Claude Code, install the Linear MCP so it can read and create issues directly.

Essential Beads commands

# See tasks with no blockers
bd ready

# Create task
bd create --title "Implement feature X" --priority P2

# See details
bd show acme-a1b2

# Close task
bd close acme-a1b2 --reason "Committed in abc123"

# List all
bd list --all

# See dependency graph
bd graph

Is it worth it?

Look, if you use Claude Code for small, isolated tasks, you probably don't need Beads. An ephemeral TodoWrite is enough.

But if you work on real projects, with long sessions that inevitably get compacted, with context that matters... then Beads is the difference between having a useful assistant and one with Alzheimer's.

And the best part: since it lives in the repo, you don't depend on any external service. If Beads disappears tomorrow, you have your data in JSON. Another nice thing is there are community UIs if you don't like the CLI: beads-ui gives you a local kanban.

Warning

Beads is new. There are reports that it doesn't work perfectly with Opus 4.5. It has worked for me, but your experience may vary.

As a sensible engineer would say: test it on a side project before committing to it.

TL;DR: Linear is for you (what to do). Beads is for your AI (how it's doing it). Together, they prevent every compaction from being a restart from zero.

Now if you'll excuse me, I need to go close some beads.

This article was originally written in Spanish and translated with the help of AI.