Bootstrap Claude Code as a SimpleFunctions Agent

When to use

• First-time setup of Claude Code as a SimpleFunctions operator
• New session that needs the safe read-only profile configured
• Reproducing the setup in CI or a new environment

Prerequisites

• Node 18 or newer
• Claude Code installed (npm install -g @anthropic-ai/claude-code or use the desktop app)
• (Optional, for write operations) SimpleFunctions account: <https://simplefunctions.dev>

Why this skill exists

The CLI has 70+ commands across read/write/trade/runtime safety classes. Claude Code with default permissions could call write commands by accident. This skill establishes the safe profile: read-only Bash allowlist, no trade/runtime/fs categories, and a verification step to confirm the loop works before anything else.

Instructions

Step 1: Install the CLI

npm install -g @spfunctions/cli
sf --version

If it says a version, install worked. If not, check which sf and Node version.

Step 2: Verify CLI without auth

These commands work without sf login:

sf world --json | jq .regime
sf scan --keyword "Fed" --json --limit 3
sf inspect KXEXAMPLE --json   # replace with a real ticker

If any fail with MissingApiKeyError, that command requires auth. Most reads are free, but world.read and a few others require SF_API_KEY (set via sf login).

Step 3: (Optional) Login for authenticated reads

sf login

Walks through OAuth or API key entry. After this:

sf me --json --detail --limit 5
sf brief --agent --json

If those return data, auth is wired up.

Step 4: Self-diagnose

sf doctor --agent --deep --json

Returns a structured health report. Look for "status": "ok" across all categories:

• localConfig
• publicHealth
• jsonContract
• commandManifest
• authReads (if logged in)
• runtimeState

If any are not ok, follow the nextActions for that category.

Step 5: Set up Claude Code Bash allowlist

For non-interactive Claude Code usage with claude -p, use a narrow Bash allowlist:

claude -p '
You are operating SimpleFunctions through shell commands.

Rules:
- Run only commands that begin with: sf status, sf doctor, sf describe, sf tools, sf me, sf brief, sf investigate, sf query, sf inspect, sf world, sf agent.
- Do not run sf buy, sf sell, sf cancel, sf intent, sf runtime, sf quoteengine, or any command that starts a daemon.
- Prefer --json for direct commands.

Task: <your task>
' \
  --tools "Bash" \
  --allowedTools "Bash(sf status:*),Bash(sf doctor:*),Bash(sf describe:*),Bash(sf tools:*),Bash(sf me:*),Bash(sf brief:*),Bash(sf investigate:*),Bash(sf query:*),Bash(sf inspect:*),Bash(sf world:*),Bash(sf agent:*)" \
  --output-format json

This is the safest default:

• Claude Code is restricted to Bash only
• The allowlist only permits read-oriented sf command families
• SimpleFunctions still enforces its own --allow / --deny policy before any tool execution

Step 6: For headless tool integration

If your harness wants to drive tool calls itself (not give Claude Code a prompt), use NDJSON mode:

sf agent --headless --deny trade,runtime,fs

This starts a stdio server. The first stdout line is a ready frame with policy + tools manifest. See sf-agent-sdk-headless skill for the protocol.

Step 7: For agent reasoning loops with safety gates

sf agent --plain \
  --new \
  --allow read,user_data,research \
  --deny trade,runtime,fs \
  --budget-usd 0.25 \
  --once "<your prompt>"

This runs ONE turn of the SimpleFunctions agent (its own LLM loop with safety policy), then exits. Use this when you want SF to reason across tools and return an analyst-style answer.

Categories:

• read — public market data, indicators, regime
• user_data — your portfolio, theses, intents
• research — investigate/query/inspect routers
• write — create thesis, signal, watchlist, alert (excludes trade)
• trade — buy/sell/cancel orders (do NOT enable for autonomous loops)
• runtime — start/stop local daemons
• fs — file system operations

Step 8: Verify end-to-end

Run this as a smoke test:

sf doctor --agent --deep --json | jq '.status'
sf describe --all --json | jq '.commands | length'
sf world --json | jq '.regime.label'
sf brief --agent --json | jq '.summary'

Expected: status ok, commands count >50, regime label string, summary populated.

Step 9: Document the local config

For other agents joining the same workspace:

SimpleFunctions setup:
- CLI installed: <version>
- Auth: <logged in / API key set / none>
- Default allowlist: read,user_data,research
- Default denylist: trade,runtime,fs
- Default budget: $0.25/turn
- Trace dir: ~/.sf/traces/

Safety model recap

For any unattended automation (cron, CI, scheduled Claude Code), enable only read,user_data,research. Never enable trade without a human approval step.

Errors and recovery

• `sf: command not found`: npm install -g may have failed. Check npm config get prefix and verify the prefix is in $PATH.
• `MissingApiKeyError`: that command requires auth. Run sf login or use the public HTTP API alternative.
• Allowlist rejection in Claude Code: missing entry in --allowedTools. Add the specific Bash(sf <verb>:*) pattern.

Related skills

• sf-morning — daily briefing once setup is done
• sf-research — first real workflow after bootstrap
• sf-agent-sdk-headless — NDJSON server protocol for tighter integration

Reference docs

• <https://docs.simplefunctions.dev/quickstart>
• <https://docs.simplefunctions.dev/cli/agentic-cli>
• <https://docs.simplefunctions.dev/build/headless-agent>
• <https://docs.simplefunctions.dev/guides/agents>