claude-inbox

EN · SK

A local inbox that lets Claude chat and Claude Code sessions (desktop app and terminal) exchange tasks, tickets and project context. One person, one machine, no network.

• Threads and tickets. The chat sends a task to a project, Claude Code asks questions, the chat answers, Claude Code closes the thread with a summary.

• Project map. Every project has a markdown card (what it is, current focus, decisions, next step) that you can edit in any editor. Chat and Code read it before they work.

• Sessions. See which Claude Code sessions are active in which project and branch.

• Status line + band. Every Code session shows 📬 api · 1 new · 2 on you · 1 waiting · 2 sessions for its own project.

Install

Requirements: Node 22+, Claude desktop and/or Claude Code.

git clone https://github.com/eodesign7/claude-inbox.git
cd claude-inbox
npm install
npm run setup -- --chat-agent=chat --wait

--wait makes setup wait until you quit the Claude desktop app (it keeps its own copy of its config and would overwrite ours). Quit it (Cmd+Q on macOS) when asked, then start it again. Setup makes a backup (*.bak-<time>) before every write and keeps your existing settings:

1. builds the project,

2. adds the claude-inbox MCP server to the Claude desktop config (macOS, Linux, Windows) with CLAUDE_INBOX_AGENT=<chat-agent> (default chat),

3. registers the server in Claude Code (scope user, no fixed identity) and installs the inbox-bar mod,

4. sets statusLine and the SessionStart / UserPromptSubmit / SessionEnd hooks in ~/.claude/settings.json (an existing statusLine is replaced and printed),

5. links the claude-inbox command globally and verifies the desktop config (desktop config OK).

The band above the prompt (inbox-bar) is installed by setup. To install only the mod from GitHub, in the Claude Code CLI: claude plugin install inbox-bar --marketplace eodesign7/claude-inbox.

Then, in every repository:

claude-inbox link <agent>     # creates the project card and ties this repo to it

Instruction blocks to paste into your chat project and your Claude Code projects are in INSTRUCTIONS.md.

Related MCP server: claude-code-bridge-mcp

How identity works

An MCP server shared by chat and Code must know who is talking:

• Claude Code session (detected by CLAUDECODE=1, which Claude Code sets for its child processes): card paths (longest prefix wins) → git repository name → folder name → default. CLAUDE_INBOX_AGENT is ignored.

• Chat: CLAUDE_INBOX_AGENT, then the same chain.

claude-inbox whoami prints the identity and where it came from. The server also prints cwd / agent / source / environment to stderr on start.

MCP tools

Files

~/.claude-inbox/
  inbox.db                        machine state: threads, messages, sessions
  projects/<agent>/card.md        project card (YAML frontmatter: name, paths, ticket_prefix)
  projects/<agent>/notes/*.md     free notes
  log/YYYY-MM-DD.md               daily log of summaries

Context lives in the markdown files (source of truth); SQLite holds only machine state.

CLI

claude-inbox map                  # overview of projects
claude-inbox show <thread_id>     # a whole thread
claude-inbox card <agent>         # open the card in $EDITOR
claude-inbox log [YYYY-MM-DD]     # daily log
claude-inbox link <agent>         # card from template + this repo's path
claude-inbox whoami               # who am I here and why
claude-inbox send <to> "text" --as <agent>

Troubleshooting

• The server is missing in the desktop app. The app overwrites its config while running. Run npm run setup -- --wait, quit the app when asked. npm run check verifies the config and the handshake.

• claude not found during setup. Setup also looks inside the desktop app's bundle; otherwise it prints the commands to run by hand.

• A Code session writes as the wrong agent. Run claude-inbox whoami in the repo and check the stderr line in ~/Library/Logs/Claude/mcp-server-claude-inbox.log (macOS). The desktop app also hands its own MCP servers to Code sessions; the chat instance tells the model not to use it from Code.

Status line labels are Slovak for now (nové = new, na tebe = waiting for you, čaká = waiting). Localization is welcome.

Development

npm test             # vitest, temporary database and configs; never touches your real ones
npm run test:mod     # tests of the inbox-bar mod (needs the `claude` CLI)
npm run build

MIT license.

Slovensky

Lokálna schránka správ medzi Claude chatom a Claude Code (desktop appka aj terminál): úlohy, tickety a kontext projektov. Jeden používateľ, jeden počítač, bez siete.

Inštalácia (Node 22+):

git clone https://github.com/eodesign7/claude-inbox.git
cd claude-inbox
npm install
npm run setup -- --chat-agent=chat --wait

--wait počká, kým ukončíš Claude desktop (Cmd+Q). Appka si drží vlastnú kópiu configu a pri ukladaní by náš zápis prepísala. Setup pred každým zápisom urobí zálohu a zachová ostatné nastavenia. Potom appku spusti a v každom repe:

claude-inbox link <agent>

• Identita: v Code session sa CLAUDE_INBOX_AGENT ignoruje; platí karta podľa paths, názov git repa, názov priečinka, default. V chate platí CLAUDE_INBOX_AGENT. Zistíš ju cez claude-inbox whoami.

• Kontext je v markdowne ~/.claude-inbox/projects/<agent>/card.md (sekcie Čo to je, Aktuálny fokus, Rozhodnutia, Ďalší krok), upravíš ho v editore: claude-inbox card <agent>.

• Nástroje, súbory a CLI sú rovnaké ako v anglickej časti vyššie. Bloky inštrukcií pre chat a Claude Code sú v INSTRUKCIE.md.

• Riešenie problémov: server v appke chýba → npm run setup -- --wait a ukonči appku; npm run check overí config.