famdeck-toolkit

Famdeck Toolkit

Setup, project initialization, and service management for the Famdeck ecosystem — a set of Claude Code plugins that add project awareness, issue routing, handoffs, multi-agent coordination, and code navigation to your sessions.

What's Included

The toolkit installs and manages these tools:

Tool	What it does	Type
Atlas	Global project registry, cross-project awareness, project metadata	Plugin
Relay	Issue routing (GitHub/GitLab/Jira/Beads), handoffs, cross-project messaging	Plugin
Context7	Up-to-date library docs via MCP plugin	Plugin
Serena	Semantic code navigation via LSP — definitions, references, rename across 30+ languages	Plugin
Beads	Git-backed issue tracker in your repo (.beads/). 30+ slash commands for issues, epics, dependencies	CLI + plugin
beads-ui	Browser-based kanban board, epic view, and search for Beads issues	Global CLI
Agent Mail	Multi-agent coordination — identities, messaging, file reservations, pre-commit guard	HTTP server + MCP
Codeman	Persistent autonomous Claude sessions — respawn controller, tmux persistence, multi-session dashboard	Web service
BMAD-METHOD	SDLC workflow framework with PM, Architect, Dev, QA personas	Per-project

Quick Start

1. Install the plugin

claude plugin install /path/to/famdeck-toolkit

2. Run setup

Inside Claude Code:

/toolkit-setup

This shows what's installed, what's missing, and lets you pick which tools to install. To install everything at once:

/toolkit-setup all

3. Restart Claude Code

Plugins and MCP servers connect on startup. Restart after first install.

4. Initialize a project

Navigate to a project directory and run:

/toolkit-init

This runs the full per-project initialization sequence:

1. Atlas — registers the project in the global registry, creates .claude/atlas.yaml
2. Relay — auto-configures issue trackers based on git remote (GitHub/GitLab/Beads)
3. Beads — initializes .beads/ issue database (bd init)
4. Agent Mail — installs the pre-commit guard (blocks conflicting file edits between agents)
5. Serena — generates .serena/project.yml with auto-detected languages, then runs onboarding
6. BMAD — installs SDLC workflow templates

Commands

Command	Description
/toolkit-setup [tool]	Install tools — interactive or by name
/toolkit-status	Show installation status of all tools + per-project state
/toolkit-init [flags]	Initialize current project (full sequence above)
/toolkit-mode [normal|readonly|ignore]	Set project init mode — full, registry-only, or skip
/toolkit-uninstall [tool|all]	Remove installed tools

toolkit-init flags

Flag	Effect
--atlas-only	Only register in Atlas
--relay-only	Only configure Relay trackers
--no-bmad	Skip BMAD installation
--non-interactive	Skip prompts, use auto-detected defaults

Beads, Agent Mail guard, and Serena always run (if their tools are installed). Use --atlas-only or --relay-only to limit scope.

Project modes

Control how /toolkit-init treats each project:

Mode	What init does
normal (default)	Full init — Atlas, Relay, Beads, Agent Mail, Serena, BMAD
readonly	Atlas only (config + registry) with .claude/ added to .git/info/exclude so nothing gets committed. For reference projects you don't develop in
ignore	Completely skipped by init scans

/toolkit-mode                # Show current mode
/toolkit-mode readonly       # Set readonly (e.g. third-party repos you reference)
/toolkit-mode ignore         # Fully exclude from init
/toolkit-mode normal         # Reset to default
/toolkit-mode --list         # List all projects with non-default modes

The mode is stored in .git/info/toolkit-mode — local only, never tracked by git, no gitignore changes needed.

Auto-Setup

The toolkit runs a SessionStart hook that:

1. Starts services — Agent Mail (port 8765) and Codeman (port 3000) if installed but not running
2. Installs missing tools — non-interactively, with a 7-day cooldown
3. Migrates legacy installs — Context7 and Serena are auto-migrated from raw MCP to plugin

This means tools stay available across sessions without manual intervention.

Tool Reference

Atlas

Maintains a central registry of all your projects at ~/.claude/atlas/registry.yaml. Each project can have a .claude/atlas.yaml with metadata (name, summary, tags, links, docs). Atlas provides the project context that other tools build on.

Key commands:

/atlas:projects        # List registered projects
/atlas:docs            # Show project documentation links
/atlas:context         # Display current project context