The manual

Getting started

You need macOS 12 or later and Claude Code. With Homebrew:

brew install alessiodonato/tap/forchetta
forchetta setup

Homebrew brings Node.js and tmux with it. forchetta setup checks tmux, Claude Code and the Xcode Command Line Tools, builds the app on your Mac and puts it in ~/Applications, then adds the hooks of Forchetta to Claude Code. It shows you every change to ~/.claude/settings.json first, and asks; answer d to see the whole diff. Built on your Mac, the app opens with no warning from macOS.

Open Forchetta from ~/Applications. The Claude Code sessions already running show up on their own, wherever you started them: in the Terminal, in iTerm, in an editor.

Sessions you can act on

Forchetta shows every session, but it can type into a session, and open its terminal, only when the session runs in its own tmux. Start a session there in one of two ways:

• in a terminal, with forchetta run claude, which takes the same arguments as claude (forchetta run claude --continue);
• in the app, with new session or new team.

A session started with plain claude is read only: its box shows what it does, and you can answer its permissions, but Forchetta cannot send it commands. Hover its box to read why.

To go through Forchetta every time you type claude, add an alias to ~/.zshrc. forchetta run uses the full path of claude, so there is no loop; command claude runs the original once.

alias claude='forchetta run claude'

Living in tmux

• Closing the Terminal window does not end the session: it only detaches it. Claude goes on, and Forchetta goes on showing it. /exit ends it.
• Ctrl-b d detaches without closing the window.
• To attach again from a terminal, open its pane in the app, or use tmux with the socket of Forchetta:
  tmux -S "$HOME/Library/Application Support/Forchetta/tmux.sock" attach -t fk-xxxxxxxx (the names come from … ls with the same socket).
• The daemon of Forchetta starts by itself. Stopping it, or quitting the app, stops no session.

After brew upgrade forchetta, run forchetta setup again: it builds the app again only when it changed.

The window

One box per session. It shows up when the session starts, fades when it ends, and goes away 10 minutes later. Each box shows:

• the project (or the name you gave it) and the state;
• the current action, Edit src/api.ts or Bash npm test for example, or what the session is asking you;
• a short summary, from the last request and the last reply;
• the context, as a bar and in tokens, and the countdown of the prompt cache (with arricurdAI);
• the cost of the session, the time since its last event, and tmux or read only.

The states

Amber, green and red only ever mean a state. Claude orange marks what you can act on: the buttons that start something, what you chose, the pane you are typing in. With “Reduce motion” on in macOS, the states stay recognizable but still. When the window is hidden, nothing moves.

Names, groups and roles

Hover a box and click ✎ to give the session a name (shown in place of the folder), a group, a role in free text, and the mark lead of the group. The choice is kept for its folder too: a session that starts again in the same folder finds its place again. Remove clears it.

With at least one group, grid / org chart appears at the top. In the org chart each group has its section, the leads above and the others below; the sessions with no group come last. A team of agents is a group too.

The terminals

Click a box to open the terminal of its session in the work area; the boxes become a column on the left. Up to four terminals stay open:

• 1: the whole area; 2: side by side; 3: the one you activated last, large on the left, the other two stacked; 4: two by two.
• The fifth click replaces the pane used longest ago. To choose every time, set "panes": { "replace": "chiedi" } in the configuration.
• ✕ closes the pane only: the session goes on in tmux and stays in the column.

Inside a terminal

• You type as in the Terminal, with the keys of Claude Code: Esc interrupts, Shift+Return starts a new line.
• Option stays Option: on an Italian keyboard it types @, # and the square brackets.
• The wheel scrolls the history of tmux. That puts the pane in tmux copy mode: scroll back to the end, or press q, to type to Claude again.
• Option + drag selects text.
• Typing in a pane keeps the keyboard there, even while Claude answers in another pane.

Commands to a session

Hover a box, or look at the header of an open pane: btw…, compact and clear. They work for sessions in the tmux of Forchetta.

• btw… opens a field for a side question; Return sends it. Its answer shows only in the terminal of the session: open takes you there.
• compact goes at once.
• clear asks first, with the tokens it will empty. With arricurdAI 0.5.0 or later, a note is written first, so the new conversation starts where the old one left off.

When a command goes

Forchetta types a command as you would, and only when it is safe. Until then it waits in the queue of the session, and the box says why (queued: /compact · waiting for the turn to end). It goes when:

• the session waits for a new prompt: never into a dialog, where a key could answer for you;
• nobody typed in the session in the last 10 seconds;
• the prompt is empty: a draft of yours blocks it until you send or delete it;
• the terminal is not scrolled back in copy mode;
• the pane still belongs to the same Claude process.

A command still in the queue can be cancelled from the box. /compact is confirmed by its hook; /clear by the end and the start of the conversation.

One command to several sessions

With at least two sessions you can act on, command to several appears at the top. Choose /compact, /clear or /btw, then the sessions: one by one, context ≥ 80%, all or none. Each one gets its command as if it came from its own box, with the same queue and the same checks.

Permissions from the box

When a session asks for a permission, its box shows the request in full, with Allow and Deny. It works for every interactive session, read only ones too.

• Allow works once, like “Yes” in the Terminal.
• always… shows the lasting choices Claude Code offers for that request (a rule, a folder, a mode), each with where it applies: this session, or the project for you or for everyone. Claude Code writes the rule. Choices for every project, and skipping all permissions, stay in the Terminal.
• Deny stops Claude, like “No”: it reads that you denied it from Forchetta, and waits for your next prompt.

The dialog stays in the Terminal too, and whoever answers first wins. Before it sends your answer, Forchetta checks that the session still waits. The buttons wake up 0.7 s after the request appears, so a click meant for something else does not answer it. Questions and plan approvals have no buttons: answer them in the terminal.

New session

new session, at the top, opens a panel. Type the folder (~/ works), pick one of the recent ones, or use Choose…. The first prompt is optional; ⌘↩ starts.

• model: Opus, Sonnet, Haiku or Fable, for that session only (--model). It does not change your default model.
• permissions: asks every time, accepts edits, auto or plan (--permission-mode).
• new worktree, with an optional name: Claude Code makes a git worktree for the session alone (--worktree). The folder must be in a git repository that Claude Code trusts.

The session starts in the tmux of Forchetta through your login shell, so it has the PATH of a new Terminal tab, and its terminal opens at once. A folder you never opened with Claude asks there whether you trust it.

Teams of agents

A team is a group of Claude Code sessions that work together. A lead gives the requests and the members carry them out. The lead is a Claude session, or you.

Create a team

1. Click new team at the top.
2. Optionally, Start from a template: developer + reviewer, feature squad (frontend, backend, tester), research + writing, or one you saved.
3. Give the team a name (it becomes its group in the org chart) and a folder.
4. Choose the lead: Claude, with a name, a role, a model and a permission mode, or you.
5. Add the members, up to 6: a name and, in one sentence, what each one does. more holds the model, the permissions and the worktree of a member.
6. For each member, choose how it talks with the lead (below), and whether the members work in their own worktree.
7. Create team, or ⌘↩.

Every session starts in the tmux of Forchetta, the lead first. From its system prompt each one knows who it is, its role, its lead and the other members. Its name shows in its box, in its pane and in Claude Code. Save as template keeps the team without its folder, to start it again elsewhere.

⇄ answers, or → executes

How the work goes

Give the goal to the lead: from the team panel, or by writing in its terminal. A Claude lead works with the tools of the team, an MCP server called forchetta that only the sessions of the team get, and that needs no permission:

Requests are delivered like the commands of the box: with the same queue and the same checks. A long one shows in the terminal of the member as [Pasted text #1 +N lines], as when you paste it yourself. When you are the lead, the answers and the questions come to you.

The team panel

team, at the top, appears when there is at least one team. It shows the thread of the team, oldest first:

• each request, with who sent it, to whom, and how it goes for each one: in the queue, working, done;
• the answers, and where they went: delivered to lead, collected by lead (waiting for it), for you, or not sent back (a member that executes only, or one that asked a question instead);
• the questions of the members.

Below the thread, write a request yourself, to the lead, to one member or to all; it arrives as “Request #n from the user:”. In the grid and in the org chart, the box of each session says what it works on (#4 from lead: Write the tests…), and the box of a Claude lead says which requests it still waits for.

Change a team while it works

edit team, in the team panel:

• → / ⇄ of a member: it applies from its next request, which tells the member.
• remove takes a member out: its requests still in the queue are cancelled and its box leaves the group. Its session goes on; /exit ends it.
• + member adds one, started like the others.
• Save as template keeps the team as it is now.

A Claude lead learns of every change with its next prompt.

Worktrees and merging

With members in own worktree, on by default, Claude Code makes a git worktree for each member, in .claude/worktrees/ of the repository, on a branch of its own. The members never touch each other's files. Each member commits its work at the end of each request; the lead stays in the folder of the team and merges the branches with git when the work is good, or tells you it is ready.

• The folder must be in a git repository. Otherwise the members share the folder.
• Claude Code makes a worktree only in a folder it trusts. If you never opened the folder with claude, only the first session of the team starts: answer the trust dialog in its terminal, and the others start, each in its worktree.

Limits

• 6 members per team, and team names are unique.
• 20 requests open at once in a team: a lead cannot hand out more work than you can follow.
• 20,000 characters per request.

Changes and conflicts

The changes of a session

When a session has written files, its box shows a button like 3 files (also in the header of its pane). It opens two views:

• by this session: each change the session made, as Claude Code reported it (edit · 3 min ago, file created);
• since the last commit: the diff of its repository, the file as it is now.

Only what was written with Edit and Write counts; a Bash command that changes files is not seen.

Conflicts between sessions

When two live sessions wrote the same file in the last hour, both boxes say so: ⚠ same file as beta: src/api.ts. Different files in the same repository give a softer warning, ⚠ same repo as beta. Two worktrees of a repository are two places, and never conflict.

Notifications and the menu bar

• A session waits for you for at least 5 seconds: a notification, and the count on the Dock icon. A click opens Forchetta on its terminal.
• A session seems stuck: “working”, but no event for 10 minutes. Its box says so, with the command in progress; so does a notification.
• A turn ends with an error, such as a rate limit: a notification that stays in Notification Center.

The fork in the menu bar shows how many sessions wait for you; its menu lists every session, with what it asks or its context and cost. ⌃⌥F shows or hides Forchetta from any app. Closing the window hides it: the app stays in the menu bar. ⌘Q quits.

Context, cache and cost

• The cost of each session, in its box, is the one Claude Code computes for /cost. It reaches Forchetta through your status line, which forchetta hooks install wraps without changing what it shows.
• Context and prompt cache come from arricurdAI, if you use it: the bar, the tokens, the countdown of the cache, and the guard badge when arricurdAI will stop the next prompt. The percentage is an estimate (≈).
• The total of today, at the top, counts every call of every session since midnight, at API prices (with arricurdAI).

Search and summaries

search, at the top, finds the passages of earlier sessions of a project that talk about your words, with their date and the request they answered. It runs arricurdai recall, which hides secrets, and only when you ask.

The summary of a box comes from the events of the session. It can come from Haiku instead, a line written only when the state changes. It is off: this is the one call Forchetta can make outside your Mac. To turn it on, set "summaries": { "haiku": true }, export your key as FORCHETTA_ANTHROPIC_API_KEY, and restart the daemon from that terminal.

Command line

forchetta --help lists the commands, and forchetta <command> --help explains each one.

The CLI uses the colors of the app; NO_COLOR=1 turns them off.

Configuration

The settings are in config.json, in the data folder. forchetta setup writes the paths; the rest is optional. Restart the daemon after a change (forchetta daemon stop && forchetta daemon start); the shortcut is read when the app starts.

Your data

Forchetta keeps what it writes in ~/Library/Application Support/Forchetta (in a clone, var/ inside it), readable only by you:

• config.json, the settings; daemon.json, the port and the token of the daemon; tmux.sock, the tmux of your sessions;
• state.json, the sessions; teams.json, names, groups and roles by folder;
• crews/, the teams of agents, one file each; crew-templates.json, your templates;
• patches/, the changes of each session; backups/, the copies of your settings; daemon.log.

Outside that folder, Forchetta writes only the app in ~/Applications and, after asking, ~/.claude/settings.json. The daemon listens on 127.0.0.1 only, and every request needs its token. Nothing about your sessions leaves your Mac; the summaries by Haiku, off by default, are the one exception.

Troubleshooting

Uninstall

1. forchetta hooks uninstall: removes only the hooks of Forchetta, after asking, and gives you back your status line.
2. forchetta daemon stop. The sessions started with forchetta run go on until you /exit them.
3. brew uninstall forchetta and brew untap alessiodonato/tap.
4. Delete ~/Applications/Forchetta.app and ~/Library/Application Support/Forchetta.