Documentation

Requirements

• macOS 27 with Apple Intelligence enabled, and the fm CLI licensed (run fm license once).
• uv, used both to install fm-pcc and to run it.
• Two saved Shortcuts for the cloud tiers — a "Use Model" action bound to Shortcut Input, followed by "Stop and Output" set to the action's response — one set to Cloud named PCC-Cloud, one set to Cloud Pro named PCC-CloudPro. Override either name with --shortcut-cloud / --shortcut-cloud-pro if yours are named differently. You don't need to build these — see Install below.
• Optional: Ollama installed and running (ollama serve) with at least one model pulled (ollama pull llama3.2) if you want the ollama model. Everything else works without it.

Install

uv tool install git+https://github.com/justwaters/fm-pcc

This puts a fm-pcc command on your PATH (run uv tool update-shell once if a fresh shell can't find it), so it works from any directory.

The first time you actually use Cloud or Cloud Pro, if its shortcut isn't installed yet, fm-pcc opens its iCloud share link for you — Cloud, Cloud Pro — tap Add Shortcut in the sheet that appears, and it'll pick up from there. On-device chat needs no setup at all.

For local development, install from a checkout instead: uv tool install -e .

Models

on-device

Calls fm respond directly, using its own --resume/--save-transcript flags to keep real multi-turn context across a conversation. No setup, works offline.

cloud

No CLI/API exists for this tier, so fm-pcc shells out to the PCC-Cloud Shortcut via shortcuts run and strips the RTF it returns. Shortcuts has no scriptable session concept, so multi-turn context is approximated by resending prior turns as plain text with each new prompt.

cloud pro

Same mechanism as Cloud, via the PCC-CloudPro Shortcut instead. The bigger, more capable cloud tier.

ollama

Talks to a local ollama serve over HTTP (/api/chat, via stdlib http.client — no extra dependency), passing real multi-turn message history natively instead of the resend-as-text approximation the Shortcuts-backed tiers need. If no model is specified, it uses whichever one ollama list returns first (--ollama-model to pick one, --ollama-host if the server isn't at the default http://localhost:11434).

Usage

fm-pcc                                    # chat TUI, starts on-device
fm-pcc --model cloud-pro                  # start the TUI on cloud pro instead
fm-pcc --model ollama                     # start on Ollama (first model 'ollama list' has)
fm-pcc --model ollama --ollama-model llama3.2  # ...or a specific one
fm-pcc respond "What is Swift?"           # one-shot, non-interactive (default: cloud-pro)
fm-pcc respond -m on-device "..."         # one-shot on-device

Flags

In the chat

Reference a local file by mentioning @path/to/file anywhere in your message (relative to wherever you ran fm-pcc, or an absolute path) — its contents get inlined into what's actually sent to the model, and fm-pcc shows an attached: ... note so you can see what went out.

you › what does @pyproject.toml say the version is?

Type / and a live palette pops up above the input, filtering as you keep typing — same as Claude Code or the Gemini CLI. ↑/↓ moves the highlight, Tab completes the highlighted command into the input, Escape dismisses it. Only a complete, exact command name turns the input text yellow — a partial like /mo doesn't, /model does.

Commands

/edit

/edit <path> <instructions> shows a diff and waits for /apply before touching disk — nothing is written automatically. It only works on-device: it uses guided generation (fm respond --schema) to get a structured line-anchored edit — a line number plus freshly-written replacement or insertion text — rather than asking the model to reproduce file content verbatim, which the on-device model is unreliable at for anything spanning more than one line. Neither cloud tier has equivalent schema control via Shortcuts, so editing isn't available there yet.

you › /edit greet.py add a docstring explaining the function

fm-pcc › Added a docstring explaining the function's purpose.

  def greet(name):
+    '''
+    This function greets a person by name.
+    '''
      print("hi " + name)

/apply to write this change to greet.py, /discard to cancel

The /task loop

/task <description> runs an orchestrator/worker loop instead of /edit's single reviewed change: Cloud Pro plans, on-device executes and writes immediately, with no per-step /apply — closer to a subagent that Cloud Pro keeps dispatching to than a one-shot assistant.

Each iteration, Cloud Pro sees the task, the full content of every file in the current directory, and a running log of what's already been done, then either says the task is done or picks one concrete next step — a file plus specific instructions. That file gets deterministically split into sections (real top-level blocks for brace languages like CSS/JS, fixed-size chunks otherwise — not model-summarized, since splitting a file into sections is exactly the kind of mechanical task a parser gets right for free and a small model doesn't). Cloud Pro picks the relevant section, and on-device drafts and writes the edit scoped to it, using the same machinery as /edit. This repeats until Cloud Pro says done or a 15-step safety cap is hit. Esc Esc stops it between steps.

This is genuinely autonomous, so it can genuinely go wrong: on real testing, a task needing cleanup or consolidation — not just clean additions — made the loop spiral. Each step can only insert or replace one line-anchored region, so instead of removing stray content from an earlier step, it kept adding more, all the way to the safety cap, leaving the file worse than when it started.

To catch this, each step's instructions are compared against the last few for suspicious similarity — in practice, a non-converging loop showed up as Cloud Pro asking for essentially the same fix again, worded slightly differently, which an exact text match wouldn't catch. If a step looks like a repeat, the loop stops immediately with a "not making progress" message instead of grinding to the cap and compounding the damage.

It's a mitigation, not a fix for the underlying cause — /task is best suited to clean, additive changes, and worth watching (or interrupting) on anything that requires cleanup.

Keybindings

The first Esc just warns you; the second, pressed within about 1.5s, actually kills the underlying fm/shortcuts process (or closes the Ollama connection) rather than merely resetting the UI — so a stopped on-device turn never finishes writing its transcript, and a stopped edit never reaches disk. Ctrl+C works the same way (first press warns, second quits), and also cancels anything running first so quitting mid-response doesn't hang waiting on it.

Limitations

• Cloud/Cloud Pro's "multi-turn context" is just prior turns re-sent as text, not a real session — it'll drift on long conversations.
• No streaming; each response is shown once it's fully generated.
• /edit and /task are on-device only — neither cloud tier supports the schema control they need.
• /task can spiral on cleanup-style tasks; see The /task loop.