Connecting FreeFlow to Claude Code
Settings → Claude Code → Connect registers FreeFlow's helper as a Claude Code hook in ~/.claude/settings.json, keeping a backup of the file. From then on a card appears whenever a session asks you something; you click or hold ⌥ and speak. Everything passes through files in your Library folder. Nothing uses the network.
What Connect changes on disk
Claude Code reads hooks from ~/.claude/settings.json, a file that is shared with every other tool you have wired into Claude Code. FreeFlow therefore parses it before touching it, refuses to write if it is not valid JSON, copies the original to ~/.claude/settings.json.bak-freeflow the first time (never overwritten afterwards), and tags every entry it adds with _freeflow: true so Disconnect can remove exactly those and nothing else. The one side effect worth knowing: programmatic editing reformats the file with sorted keys and two-space indentation. The original bytes are in the backup.
| Event | Matcher | What the card shows |
|---|---|---|
PreToolUse | ExitPlanMode|AskUserQuestion | A plan to approve, or a question with its options |
PermissionRequest | — | A command or tool Claude wants to run (click-only) |
Stop | — | Claude's finished turn, with a field to reply |
UserPromptSubmit | — | Housekeeping: you answered in the terminal, so the card closes |
SessionEnd | — | Housekeeping: the session ended, so its cards go |
What happens when Claude asks
- Claude Code runs
freeflow-agent-hookand blocks on it, passing the event as JSON on stdin. - The helper checks that a live FreeFlow holds the agent lock. If not — never connected, quit, crashed — it exits immediately and Claude prompts you itself.
- It writes the payload atomically to
~/Library/Application Support/FreeFlow/agent/inbox/and polls for a response file every 50 ms. - FreeFlow shows the card on your active Space. The card cannot take keyboard focus, so your cursor stays where it was.
- You click an option, or hold ⌥ and say it. On a question, saying an option's name picks it; anything else is sent as a free-form answer. Permission cards take clicks only.
- FreeFlow writes the response; the helper prints it to stdout and exits 0. Both files are deleted.
Saying “Always” on a permission
A permission card offers Allow, Always and Deny. Always appends one rule to the project's own .claude/settings.local.json — the same file Claude Code writes when you choose “always allow” in its prompt — so the grant behaves identically however it was made, and it stays with that project rather than following you into another repository. The card shows you the exact rule before you click.
Switches
- Plans and questions, Permissions, Finished turns — each card type has its own switch in Settings → Claude Code, and changes apply at once.
- Disconnect removes FreeFlow's tagged entries and any event key it emptied, and leaves the rest of the file exactly as it found it.
- Incognito does not affect the bridge: cards are not transcripts, and nothing about them is kept.
When a card does not appear
- Settings says “Not connected” although you connected before. You moved FreeFlow.app. The hook entries point at the helper's absolute path, so a move makes every hook yield. Click Connect again; it converges the path.
- Cards appeared once and then stopped. Check that FreeFlow is still running — the menu bar mark should be there. The helper yields instantly when it is not.
- The card is on another Space. Fixed in 1.7.2: the card now moves to whichever Space is active when it appears. Update if you are on 1.7.1 or earlier.
- Claude Code says a hook failed. It should never say that about this one: the helper exits 0 on every path. If it does, send feedback from the app with diagnostics on.
- `~/.claude/settings.json` is not valid JSON. FreeFlow refuses to touch it and says so. Fix the file in an editor, then Connect again.
Questions people ask
Can I see exactly what FreeFlow added to settings.json?
Yes. Open the file; every FreeFlow entry carries "_freeflow": true. The pre-FreeFlow copy is settings.json.bak-freeflow in the same folder.
Does the hook send anything over the network?
No. The helper and the app exchange JSON files under your Library folder. There is no port, no daemon and no server.
Can I answer a question with a free-form sentence?
Yes. If what you say does not match an option's name, it is sent as a free-form answer. Saying an option — even loosely — selects it.
Why can I not answer a permission card by voice?
Because a misheard word must never run a command. Permissions accept clicks only; that is a deliberate limit, not a missing feature.