Beads (beads)
AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple CLI commands.
- Type
- Plugin
- Repository
- gastownhall/beads
- GitHub stars
- 27.5k
- License
- MIT
- Repo last updated
- Sep 27, 2026
- Source file
- plugins/beads/.claude-plugin/plugin.json
- Version
- 1.3.0
- Author
- Steve Yegge
What Beads (beads) is
Beads (beads) is a plugin published in the gastownhall/beads repository on GitHub, which has about 27.5k stars. The repository describes itself as: “Beads - A memory upgrade for your coding agent”
A plugin is a package that bundles skills, slash commands, subagents, hooks, and MCP connectors so they install together. Plugins are plain files with a manifest at .claude-plugin/plugin.json, and they work in both Claude Code and Claude Cowork.
Installing Beads adds everything it ships in one step. Connectors inside a plugin still need to be connected separately, and hooks and subagents only run in Cowork and Claude Code, not in regular chat.
How to install Beads (beads)
Claude Code
- Add the repository as a plugin marketplace: claude plugin marketplace add gastownhall/beads
- Install the plugin: claude plugin install beads@<marketplace-name>, using the marketplace name from the repository's .claude-plugin/marketplace.json.
- Restart the session if the new skills or commands don't appear straight away.
Claude Cowork
- Open Customize → Plugins and choose Add marketplace.
- Enter gastownhall/beads (the owner/repo shorthand works for GitHub).
- Find Beads in the list, click Install, then connect any connectors it needs from its Connectors tab.
New to extending Cowork? Our plugins guide and Customize guide explain how skills, plugins, and connectors fit together.
Inside the source file
An excerpt from plugins/beads/.claude-plugin/plugin.json, shared under the repository's MIT license. Read the full file on GitHub.
This is the shared Claude/Codex plugin package for Beads. Claude and Codex use separate manifest files, but they share the same skill tree.
Layout
- .codex-plugin/plugin.json describes the Codex plugin.
- .claude-plugin/plugin.json describes the Claude plugin.
- skills/beads/ contains the plugin-owned Beads skill.
- .codex-plugin/hooks/hooks.json contains Codex-only lifecycle hooks for startup and compaction-aware context refresh.
- The Claude marketplace entry lives at .claude-plugin/marketplace.json.
Codex Hooks
The Codex plugin exposes native hooks through .codex-plugin/plugin.json, which points at .codex-plugin/hooks/hooks.json. With Codex 0.129.0+, /hooks shows these lifecycle handlers:
- SessionStart runs bd codex-hook SessionStart for startup|resume|clear and injects full bd prime output.
- PreCompact runs bd codex-hook PreCompact for manual|auto and warns if bd prime --memories-only cannot run.
- PostCompact runs bd codex-hook PostCompact for manual|auto and records a one-shot refresh marker in the user cache/temp directory.
- UserPromptSubmit runs bd codex-hook UserPromptSubmit and, when a refresh marker exists, injects full bd prime output once before clearing it.
If the plugin is not installed, bd setup codex writes an equivalent .codex/hooks.json fallback and enables [features].hooks = true.
Local Development
Claude Code uses .claude-plugin/marketplace.json, which points at this shared package root.
Before you install
- Read the whole file first. Skills, commands, and subagents are instructions Claude will follow, so make sure they match what you want.
- Check which tools, scripts, or MCP servers it uses. Local servers and scripts run with your permissions.
- Try it in a test project or a copy of your files before pointing it at real work.
- Pin the version you tested, and review changes before updating.
- Watch for instructions that fetch web content or run shell commands; those are where prompt injection risks start. See our prompt injection guide.
FAQ
What is Beads (beads)?
Beads (beads) is a plugin for Claude Code and Claude Cowork from the gastownhall/beads repository on GitHub. AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple CLI commands.
How do I install Beads (beads) in Claude Code?
Add the repository as a plugin marketplace: claude plugin marketplace add gastownhall/beads Install the plugin: claude plugin install beads@<marketplace-name>, using the marketplace name from the repository's .claude-plugin/marketplace.json. Restart the session if the new skills or commands don't appear straight away.
Can I use Beads (beads) in Claude Cowork?
Open Customize → Plugins and choose Add marketplace. Enter gastownhall/beads (the owner/repo shorthand works for GitHub). Find Beads in the list, click Install, then connect any connectors it needs from its Connectors tab.
Is Beads (beads) safe to install?
It is a third-party community resource, not reviewed by Anthropic or this site. Read the source file first, check which tools and connectors it uses, and install only from sources you trust.
Similar resources
- Beads — Deliberately Short Entry Point A model of restraint: the file opens by stating it is intentionally short, links the canonical AGENTS.md / instructions / architecture… CLAUDE.md Example · gastownhall/beads
- Beads Dolt-powered issue tracker for multi-session work with dependencies and persistent memory across conversation compaction. Use when work spans sessions, has blockers, or needs context recovery after compaction. Trigger with "create task", "what's ready", "track this work", "resume after compaction". Make sure to use this skill whenever managing multi-session work, tracking dependencies, or… Skill · gastownhall/beads
- Planning With Files Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Works… Plugin · OthmanAdi/planning-with-files
- Cybersecurity Skills 818 cybersecurity skills covering web security, pentesting, DFIR, threat intelligence, cloud security, malware analysis, and more. Plugin · mukul975/Anthropic-Cybersecurity-Skills
- Pm Ai Shipping AI Shipping Kit — for PMs and founders accountable for AI-built code. Document a vibe-coded app, review it for correctness, security and performance defects, and produce a reviewer-ready shipping packet. Plugin · phuryn/pm-skills
- Terraform The Terraform MCP Server provides seamless integration with Terraform ecosystem, enabling advanced automation and interaction capabilities for Infrastructure as Code (IaC) development. Plugin · anthropics/claude-plugins-official
- Pm Data Analytics Data analytics skills for PMs: SQL query generation and cohort analysis. Analyze user data, generate queries, and identify retention patterns. Plugin · phuryn/pm-skills
- Telegram Telegram channel for Claude Code — messaging bridge with built-in access control. Manage pairing, allowlists, and policy via /telegram:access. Plugin · anthropics/claude-plugins-official