Tools

Read a text file from disk and return it with cat -n style line numbers.

• ›Output is six-digit line number, tab, content — the model navigates by line number when it hands old_string back to Edit.
• ›Refuses files over 10 MB and binary files (null-byte sniff on the first 8 KB).
• ›Honours offset (1-indexed) and limit so the agent can page large files instead of truncating.

Write or overwrite a file. Creates parent directories. Atomic via temp-file + rename.

• ›Short-circuits when the new content is byte-identical to the existing file — no prompt, no churn.
• ›Preserves the existing file mode on overwrite.
• ›Refuses payloads above 50 MB to keep the approval prompt meaningful.

Exact-string replacement. old_string must be unique unless replace_all is set.

• ›If old_string matches more than once, Edit refuses with a count and asks for more context — silent first-match-wins is a common source of broken refactors.
• ›no-op edit (old_string == new_string) is rejected before any prompt.
• ›Atomic write into a sibling tmp file in the target directory, then rename — file mode is preserved.

Replace, insert, or delete a cell inside a Jupyter notebook (.ipynb).

• ›Targets a cell by id or by 0-based index; insert defaults to end-of-notebook when neither is given.
• ›Mutating a code cell wipes its stale outputs and execution_count automatically.
• ›Notebook is parsed as JSON, mutated in place, and written atomically — a crash mid-write cannot leave a half-written .ipynb on disk.

Execute a POSIX shell command. Captures stdout+stderr with a configurable timeout.

• ›Streams output incrementally — long-running commands show progress in the transcript instead of going dark.
• ›Default timeout 120 s, max 600 s. Output capped at 30 000 characters with a marker; the pipe is drained past the cap so the child doesn't block.
• ›Spawns the child in its own process group; on timeout the entire group is SIGKILLed — no orphaned tail processes.
• ›An informational denylist (rm -rf /, sudo rm, mkfs, dd if=, fork bombs) prepends a [danger confirmed] note to the result if you approve one of those.

Search file contents with a regex. Uses ripgrep when available, Python re fallback otherwise.

• ›Three output modes: files_with_matches (default), content (with line numbers), and count.
• ›Both implementations skip .git, node_modules, .venv, __pycache__, dist, build, and the usual cache dirs.
• ›head_limit caps the result list — by default 100 — so a hot regex on a monorepo can't blow the context window.

Find files matching a glob like src/**/*.py. Returns absolute paths sorted by mtime desc.

• ›mtime-desc ordering means recently-edited files come first — useful when the agent is hunting for what changed.
• ›Same ignore-dir list as Grep so vendor noise never makes it back.
• ›Coerces stringified nulls (path: "null" / "none" / ".") to ctx.cwd — defensive against models that JSON-stringify their nulls.

List a directory with type indicators — name/ for dirs, name@ for symlinks.

• ›Hidden files are skipped unless the target directory itself is hidden.
• ›Caps at 1000 entries — anything past that gets truncated rather than streamed.
• ›Refuses files (suggests Read) and refuses non-directories with a clear error.

Fetch a URL and return its text content (HTML stripped to markdown-like text).

• ›Upgrades http:// to https:// before issuing the request.
• ›Follows redirects, surfaces 401 / 403 explicitly, and returns the cleaned text body — not the raw HTML.
• ›Pairs well with the prompt argument so the agent can call WebFetch with a why, not just a URL.

Issue a keyword query and return ranked title / snippet / URL rows.

• ›DuckDuckGo HTML endpoint by default; swap providers via FULCRUM_SEARCH_PROVIDER (planned).
• ›Supports allowed_domains and blocked_domains so you can scope a search to docs.python.org without scraping the whole web.
• ›Unwraps DDG's /l/?uddg= redirector so the URLs returned to the model are the real destinations.

Persist a memory entry that future sessions will see in their system prompt.

• ›Four types — user (identity / role), feedback (rules they've given you), project (current effort), reference (external pointers).
• ›Stored as one markdown file per entry plus a top-level MEMORY.md index.
• ›The index is auto-injected at session start; only the one-line description is in the prompt — the full body is loaded by ReadMemory.

Load the full body of a saved memory by filename.

• ›Pass the filename with or without .md.
• ›Use this when an index entry's description sounds relevant to the current task — the body isn't in the prompt by default.

List currently saved memories with their type and one-line description.

• ›Optional type filter restricts the list to one of user / feedback / project / reference.
• ›Useful as a discovery step before ReadMemory pulls the full body.

Delete a memory entry by file name.

• ›Approval-gated even though the file is in your home dir — accidental memory loss is hard to recover from.

Spawn a sub-agent with a fresh context window and run a focused task to completion.

• ›Sub-agent inherits the parent's REGISTRY minus Agent / EnterPlanMode / ExitPlanMode (no infinite recursion).
• ›subagent_type='<name>' loads a profile from ~/.fulcrum/agents/ or ~/.claude/agents/. Profile sets the system prompt, tool whitelist, and model — and overrides any tools or model arg passed inline.
• ›Streaming events from the sub-agent are collected; the tool returns the assembled final text to the parent agent.

Save a named sub-agent profile to ~/.fulcrum/agents/<slug>.md.

• ›Profile = YAML frontmatter (name, description, tools, model, whenToUse) + a markdown body that becomes the agent's system prompt.
• ›Pass overwrite=true to replace an existing profile of the same name.

List every available sub-agent profile with role, tools, model, and source path.

• ›Reads ~/.fulcrum/agents/, ~/.claude/agents/, and any plugin-supplied agents.
• ›Use this before Agent + subagent_type so you call a real profile instead of guessing.

Delete a user-dir agent profile by name.

• ›Claude Code agents and plugin agents are read-only here — you can only delete things you saved with SaveAgent.

Execute a named skill from ~/.fulcrum/skills/.

• ›The tool's own description is rebuilt at runtime to list every loaded skill — so the model sees which slugs it can call without a separate discovery step.
• ›Optional args string is appended to the skill body so a single skill can take parameters.

Create a new skill at ~/.fulcrum/skills/<slug>.md.

• ›Frontmatter supports whenToUse (when the agent should reach for it), allowedTools (restrict the skill's tool surface), and model (override the active model just for this skill).

List every available skill with description and source path.

• ›Bundled and user-dir skills are merged — the path tells you which is which.

Delete a user-dir skill by name.

• ›Bundled skills cannot be deleted — they reappear on next start.

Ask the user a question mid-task and read the response.

• ›V1 stub: routes through ctx.approve and returns yes / no.
• ›Phase 3 will upgrade this to a TUI question widget with free-form and multiple-choice replies.

Summarize a block of text into a compact brief via the LLM.

• ›Useful when a long shell output or web page is about to bloat the context window — Brief boils it down before the next turn.
• ›Preserves file paths, decisions, and numeric values; everything else is fair game to compress.
• ›max_tokens is a soft cap with a 4-chars-per-token heuristic.

Submit a proposed plan for user approval before executing further tool calls.

• ›Sets a module-level _current_plan flag; Phase 3 of the agent loop will gate execution on it.
• ›Pair with ExitPlanMode to resume normal tool execution once the user signs off.

Exit plan mode and resume normal tool execution.

• ›Clears the _current_plan flag — no payload required.

Append items to the session todo list shown in the TUI sidebar.

• ›Each item carries a status — pending, in_progress, or completed.
• ›Persists at ~/.fulcrum/sessions/<session>/todos.json (or ~/.fulcrum/todos.json when no session id is set).

Create a new task in the session task registry.

• ›Fields: title, active_form (a present-tense progress label), optional description, optional dependencies on other task ids.

List tasks in the session registry, optionally filtered by status.

• ›Read-only snapshot — useful before TaskUpdate or TaskStop.

Fetch a single task by id with full details.

• ›Returns the full record — title, description, output, owner, status — not just the summary line.

Update a tracked task's status, description, or output.

• ›The output field captures the artifact a task produced (a path, a diff, a finding) so a later task can consume it.

Cancel a task — sets its status to CANCELLED.

• ›Doesn't touch dependencies — downstream tasks see the cancellation and decide for themselves.

Create a scheduled job (5-field cron syntax or @once <ISO> for one-shot).

• ›V1 records the schedule on disk at ~/.fulcrum/cron.json — an external runner is required to actually execute jobs.
• ›Each job carries a prompt that will be fed to fulcrum exec when it fires.

Delete a scheduled cron job by id.

• ›ID comes from CronList — names are not unique.

List every scheduled cron job.

• ›Shows id, name, schedule, enabled flag, and last run timestamp.

Watch a long-running shell command's output until a regex matches or the timeout fires.

• ›Use cases: tailing logs, polling for build completion, waiting for a dev server's ready line.
• ›Spawns the child in its own process group; on match or timeout the entire group is killed cleanly.
• ›Returns a [matched] / [exit N] / [timeout] prefix plus the captured output, capped at 30 000 chars by default.

Pause execution for a bounded duration.

• ›Clamped to [0, 600 000] ms — an over-eager model cannot wedge the loop with a multi-hour wait.
• ›Useful for letting a deploy propagate or a file watcher debounce before the next tool call.

Create a git worktree on a new or existing branch.

• ›Defaults the path to ../<repo>-<branch> and the base ref to HEAD.
• ›Returns the worktree path; subsequent file ops should target it explicitly.

Remove a git worktree, optionally deleting the associated branch.

• ›Recovers the branch name from git worktree list --porcelain before removal so delete_branch can target the right ref.
• ›Pass force=true when the worktree has uncommitted changes.

Code intelligence via Language Server Protocol — go-to-definition, find references, hover, document symbols.

• ›Four operations: definition, references, hover (markdown), symbols (the document outline).
• ›Server is selected by file extension; if none is registered or installed, the call fails with a clear diagnostic.
• ›Read-only — never prompts.

Enumerate resources across configured MCP servers.

• ›Pass server to restrict to one server; omit to fan out across all configured servers.
• ›Servers that fail to connect are logged inline in the output instead of aborting the whole call.

Read a resource by URI from a configured MCP server.

• ›Concatenates any text content items the server returns; binary blobs are summarised as [binary blob, N chars base64].

Authenticate against an MCP server.

• ›V1 stub: returns instructions for hand-editing ~/.fulcrum/mcp.json (bearer tokens for stdio servers, custom headers for sse / http).
• ›OAuth device flow is deferred to a later phase.

Keyword search across the tool registry. Returns matching tools and their schemas.

• ›Name matches outweigh description matches by 100x — short, well-named tools rank above tools whose body happens to mention the query.
• ›Truncates each schema to 300 chars so the result fits in a single context turn.

Evaluate Python code in a session-scoped persistent namespace.

• ›State persists across calls within one session — one fulcrum session == one Python process == one shared namespace.
• ›reset=true wipes the namespace and starts clean.
• ›stdout / stderr are captured; output is capped at 30 000 chars.

Describe an image at a local path using the configured vision model.

• ›Reads PNG, JPEG, GIF, WEBP, BMP and base64-encodes them as a data URL for the vision model (Llama-4-Maverick on scx.ai by default).
• ›image_path='clipboard' reads the macOS clipboard image — handy for screenshots whose temp file was reaped before the agent saw it.
• ›Handles macOS quirks: drag-drop backslash escapes, U+202F narrow-no-break-space in screencapture filenames, and TCC permission denials with a useful diagnostic.

Emit arbitrary structured data to the caller without invoking other side-effects.

• ›Supports JSON, YAML (when pyyaml is installed; falls back to JSON otherwise), and plain text.
• ›Useful for orchestration patterns where the agent's caller wants a machine-readable answer rather than prose.