DocsHow it works›

Docs · Get started

How it works

Fulcrum is a Python TUI that hosts an agent loop. The agent reads a system prompt, your prompt, and the conversation history, picks tools, runs them locally, and streams the result back as a chat message. Models live on scx.ai (sovereign Australian infrastructure). Tools — file I/O, shell, search, MCP — live on your machine. The split is the whole product: code never leaves your laptop, inference never leaves Australia.

The agent loop

One turn is a streamed call to /v1/chat/completions. If the response contains tool calls, Fulcrum runs each one locally, appends the result to the message history, and calls the model again. Repeat until the model returns plain text without tool calls — that becomes the assistant's reply.

Fulcrum agent loopUser prompt feeds into context (memory, skills, history), which feeds into an LLM call to scx.ai. If the model returns tool calls, Fulcrum runs the tool locally and feeds the result back into the next LLM call. Otherwise the text streams to the user and the turn ends.user promptTUI inputcontextmemory + skills + historyLLM callscx.ai · streamedtool calls?in stream?nostream textdoneyesrun tool locallyfiles · shell · web · MCPtool result → next turn (loops)agent loop · pick tool → run locally → reply with result → repeat

What runs where

The boundary is hard. Inference is the only thing that leaves your machine, and only because GPUs cost more than laptops do. Everything else — including the entire tool surface — runs in the same process as the TUI.

Where Fulcrum runsTwo columns. Left: on your machine — TUI, file I/O, shell, search, MCP, voice capture. Right: on scx.ai — chat completions, vision, whisper, TTS, gateway key issuance. An arrow labelled HTTPS connects the two.On your machinefulcrum process · 0.0.0.0 nothing· TUI · prompt · transcript· Read · Write · Edit · Glob · Grep· Bash · ripgrep search· MCP servers (stdio + SSE)· voice mic capture· ~/.fulcrum/ config + memory· skills · plugins · hooksOn scx.aiapi.scx.ai · AU-hosted GPUs· /v1/chat/completions· vision (Llama-4-Maverick)· /audio/transcriptions (Whisper)· /audio/speech (TTS)· gateway key issuance· rate limit + audit logHTTPStokens only

Tools include Read, Write, Edit, Glob, Grep, Bash, WebFetch, WebSearch, NotebookEdit, Memory, MCP dispatchers, and the rest. The agent loop dispatches each tool call to its implementation; the model never sees a syscall, only a JSON result. See tools reference for the full toolbelt.

Anatomy of a turn

Sequence diagram. Mint moves are the assistant; amber moves are the tool runner. The TUI is just a humble messenger between them.

One Fulcrum turn, lifeline viewThree lifelines: TUI, scx.ai, and tool runner. The TUI POSTs to /v1/chat/completions, scx.ai streams deltas, the TUI dispatches a tool call to the tool runner, the tool returns, the TUI POSTs again, scx.ai streams the final text.TUIscx.aitool runnert0POST /v1/chat/completionst1stream deltas (SSE)t2dispatch Tool.run({name, args})t3ToolResult (json)t4POST again, with tool message appendedt5stream final text · finish_reason=stoploop t2–t4 once per tool call in the response

A turn that needs no tools collapses to t0 → t1 → done. A multi-step refactor can ping-pong between scx.ai and the tool runner a dozen times in one user turn — each round-trip is the same shape.

Streaming and interruption

Every assistant turn streams. Token deltas arrive as SSE events; the TUI paints them straight into the transcript. Tool calls render as collapsible blocks the moment the arguments finish parsing, so you see what the agent is about to do before it does it.

To kill an in-flight turn: /cancel or Ctrl+C. Cancelling kills the agent worker, stops the spinner, drops any partial assistant message, and re-focuses the prompt input. Tool calls in flight at the moment of cancellation are abandoned — their results never make it into the transcript.

Where state lives

Everything Fulcrum persists is under ~/.fulcrum/, plus per-project memory files in your repo root. No database, no cloud sync, no hidden home directory — back it up with tar.

ThingPath
Config~/.fulcrum/config.json
Memory~/.fulcrum/memory/
Skills~/.fulcrum/skills/ (custom) + bundled with the binary
Plugins~/.fulcrum/plugins/
Hooks~/.fulcrum/hooks.json
Logs~/.fulcrum/logs/fulcrum.log
MCP servers~/.fulcrum/mcp.json
Sessions~/.fulcrum/sessions/
Per-project memory<repo>/CLAUDE.md and <repo>/AGENTS.md

The scx.ai key lives outside this tree on purpose: it's stored in the OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager) via keyring, with an encrypted-file fallback at ~/.fulcrum/scx.enc when no keychain backend is available. See models · API key flow for the full handshake.

Next steps

  • Tools → The full toolbelt — what each tool does, when the agent picks it, what arguments it takes.
  • Memory & knowledge → How ~/.fulcrum/memory/, project-level CLAUDE.md, and skills get injected into the system prompt.
  • Voice & speak → /voice mic capture, /speak TTS, voice picker.
  • Models → The scx.ai catalogue and how Fulcrum routes between chat, vision, transcription, and TTS.