Butler

English | 简体中文

A desktop "work butler" for people who run several Claude Code sessions at once, one per ticket. macOS (Apple silicon) and Windows (x64). MIT licensed. Website: butler.statecore.io.

Tickets can be grouped into features, and features into epics. Talk an epic through in an epic session and it creates the features with their plans; a feature's coordinator session then creates the tickets, opens a session in each and hands it its task. Sessions don't talk to each other directly. They share layered memory in a local StateCore store, so the progress and decisions one session saves can be read by the others in the same ticket, feature or epic. The Now page lists what every session is doing, by epic, feature and ticket, with the ones that need you at the top. Each night Butler writes a handoff for every ticket that moved.

Local-first. Butler keeps its data in local SQLite files. Data leaves your machine only through your own claude and, if you configure one, a personal LLM API. That API is called only at the Full privacy level, for memory distillation, and every call it receives is logged on an audit page.

Language. The UI comes in English and Chinese. It follows your system language at first (Chinese for any Chinese locale, English otherwise); change it under Settings → General → 语言 / Language or on the first-run wizard. The language also switches the default prompts Butler sends to claude, so handoffs and memory notes are written in that language; prompts you edited yourself are kept. Installs upgraded from 1.2.0 or earlier stay in Chinese until you change it. After switching, click Install / repair in the environment check once so the /handoff command is rewritten in the new language. This README quotes the labels of the English UI; the Chinese README quotes the Chinese ones.

How Butler compares

Running several Claude Code sessions side by side, each in its own git worktree, is now common: Claude Code's own desktop app does it, and so do tools such as Conductor and Claude Squad. Butler does that too, but it is built around the work rather than the agents:

• Work, not sessions. Sessions belong to tickets, tickets to features, features to epics. A plan agreed in an epic session reaches the next feature's coordinator together with the progress, decisions and open questions of the features before it.
• Memory that outlives a session. Every session can recall what earlier sessions of its ticket, feature or epic saved, so no session has to write a document for the next one to read. Long sessions are handed off, cleared and resumed from that memory.
• You stay in the loop. The Now page puts the sessions that wait for you first. A session that has stopped moving is flagged with its likely cause, and nothing is fixed until you click.
• Fewer collisions. The merge coordinator holds a merge back when it would conflict with another ticket's branch in the same repo.
• Handoffs written for you. Every night, and when you type /handoff, Butler has your own claude write a structured handoff per ticket and a progress summary per feature.

Butler works with Claude Code only.

What it does

• Tickets first. Each ticket has its worktree or branch, its Claude Code sessions (embedded terminals), its PR state and its after-merge follow-ups. Sessions you started outside Butler in the last 7 days show up under Unclaimed sessions, so you can attach them to a ticket. A ticket can span several repos (say, a frontend and a backend): create it with or without a repo, then add more on the ticket page. Each repo has its own work mode and branch, and Edit changes them later. A new session asks which repo to work in. A running session, including one a coordinator started, has an × next to its button: click it twice to end that session. Its conversation is kept, and clicking the button opens it again. A session that is not running can be hidden with the same ×. It only leaves the list (its conversation is kept), and Hidden brings it back. Sessions that Butler opens do not stop at Claude Code's question about which servers from a repo's .mcp.json to enable: Butler enables them, except the ones you turned off in that repo before. A coordinator session runs in the ticket's workspace folder (~/.butler/workspaces/<ticket>) and sees every repo through --add-dir. All sessions of a ticket share its memory. The coordinator also gets a butler-sessions MCP server with five tools:
• list_repos lists the ticket's repos.
• start_session opens a new session in one repo and sends it a task as its first message. The new session appears under the same ticket, where you can watch it, take over and answer its permission prompts.
• list_sessions shows what each session is doing.
• session_activity shows one session's activity plus its last command output (up to 4 KB).
• end_session closes a session of the ticket that is done, the same as clicking its ×. It refuses a session that is still working, one showing a prompt that waits for you, one that isn't running, and the caller itself.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗