FreeFlowDownload
Docs · Claude Code

Connecting FreeFlow to Claude Code

By Yiftach FreemanUpdated 4 min read

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.

The hook entries FreeFlow registers
EventMatcherWhat the card shows
PreToolUseExitPlanMode|AskUserQuestionA 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
Each entry runs the helper at its absolute path inside FreeFlow.app with a 130-second timeout. The three card events have switches in Settings; the two housekeeping events ride along whenever anything is connected.

What happens when Claude asks

  1. Claude Code runs freeflow-agent-hook and blocks on it, passing the event as JSON on stdin.
  2. 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.
  3. It writes the payload atomically to ~/Library/Application Support/FreeFlow/agent/inbox/ and polls for a response file every 50 ms.
  4. FreeFlow shows the card on your active Space. The card cannot take keyboard focus, so your cursor stays where it was.
  5. 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.
  6. 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

When a card does not appear

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.

Sources

Try FreeFlow free for 14 days$99 once, three MacsNo card, no account. macOS 14+ · Apple Silicon.
Download now