Fuji: A minimal harness to deploy agents at scale

Fuji, a minimal agent harness written in Go, provides an embeddable, headless runtime with bundled tools for deploying agents at scale, supporting one-shot CLI mode and cron scheduling. The tool, which integrates with Anthropic and OpenAI-compatible providers, enables deterministic tool execution and session continuity, with exit codes for automation. Fuji's design eliminates the need for a daemon or process manager, allowing simple cron entries to run agent tasks such as nightly repo-health checks.

fuji is a pure, naked core for agentic work at scale. Written in Go, it delivers an embeddable, headless agent runtime with bundled tools for a guaranteed agentic experience across fleet deployments. Pure Naked Core : Lightweight, single-threaded execution engine without heavy framework dependencies, dynamic plugin runtimes, or interactive TUI overhead. Guaranteed Bundled Tools : Standardized, deterministic tool implementations read , write , edit , bash , grep , find , ls , git with embedded tool support to eliminate host environment drift. Embeddable & Headless : Usable as a Go library or as a one-shot CLI designed for automation, batch pipelines, and fleet orchestrators. Provider Agnostic : Direct HTTP/SSE streaming integrations for Anthropic and OpenAI-compatible providers with custom base URL support. Session Continuity : Full JSONL v3 session compatibility compatible with standard session logs supporting branching, compaction, and resumes. Build the static binary: go build -o fuji ./cmd/fuji Configure your model provider API key via environment variables: Anthropic export ANTHROPIC API KEY="your-anthropic-key" Or OpenAI export OPENAI API KEY="your-openai-key" Run fuji in one-shot mode: Direct prompt string fuji run --prompt "Fix failing tests in pkg/session" Prompt from a file fuji run --prompt @task.md --cwd /path/to/repo --model claude-sonnet-4-5 Because fuji runs headless and exits cleanly with a predictable exit code, dropping a job into cron is trivial — there is no daemon or TUI to keep running. Here's a crontab entry that runs a nightly repo-health check: m h dom mon dow command 0 3 cd /path/to/repo && /opt/fuji/fuji run --prompt @task.md --cwd /path/to/repo --model claude-sonnet-4-5 /var/log/fuji.log 2 &1 Just one line. The one-shot fuji run runs the entire agent task to completion, exits with a code you can act on 0 success, 2 runtime failure , and logs are simply appended to a file. No supervisor, no process manager — plain cron is enough. For finer scheduling control within a single day e.g. every 15 minutes , cron's step syntax works the same way: /15 /opt/fuji/fuji run --prompt "Commit any staged changes" --cwd /path/to/repo /var/log/fuji.log 2 &1 To install it interactively as your current user: crontab -e paste a line above, save, and exit And confirm your job is scheduled: crontab -l That's all there is to it — a full agentic job, scheduled and running with the tools your system already ships. Usage: fuji run --prompt <text|@file flags... Run one agent task fuji version Print version fuji help Show help Flags: --prompt <text|@file Prompt text, or @path to a prompt file required --cwd <dir Working directory default: current directory --session <path Resume an existing session file --skills <dir Path to custom skills directory .fuji/skills --model <id Model identifier e.g. claude-3-7-sonnet-20250219, gpt-4o --provider <id Provider: anthropic default or openai --base-url <url Custom provider API base URL --thinking <level Thinking level: off | minimal | low | medium | high | xhigh | max --timeout <secs Per-turn timeout in seconds --app-url <url App attribution URL OpenRouter HTTP-Referer, required for rankings ; auto-set when --base-url is OpenRouter --app-title <name App display name OpenRouter X-OpenRouter-Title ; auto-set to "fuji" when --base-url is OpenRouter --app-categories <list App marketplace categories, comma-separated OpenRouter X-OpenRouter-Categories --tools <list Comma-separated allowlist of tools --no-tools Disable all tools --log-level <level Log level: debug | info | warn | error emits JSONL to stderr 0 : Success task completed normally 1 : Configuration or authentication error 2 : Runtime failure 3 : Aborted SIGINT / cancellation fuji guarantees the following standard tools across all environments: | Tool | Description | |---|---| read | Read file contents text or images with offset/limit pagination | write | Create or overwrite files auto-creates directories | edit | Atomic search-and-replace edits with mutation serialization | bash | Execute shell commands with configurable timeouts and streaming output | grep | Fast regex and literal file search powered by ripgrep | find | Locate files matching glob patterns | ls | Directory listing with file metadata | git | Execute Git operations | Embed fuji directly into your Go services: package main import "context" "log" "fuji/pkg/config" "fuji/pkg/session" func main { cfg := config.Config{ Cwd: ".", Provider: "anthropic", Model: "claude-3-7-sonnet-20250219", ApiKey: "your-api-key", } sess, err := session.New cfg if err = nil { log.Fatalf "failed to create session: %v", err } defer sess.Close if err := sess.Prompt context.Background , "Analyze this repo and summarize it" ; err = nil { log.Fatalf "agent loop error: %v", err } } fuji merges configuration in order of increasing precedence: - Defaults - User config ~/.fuji/config.json - Project config <cwd /.fuji/config.json - Environment variables ANTHROPIC API KEY , OPENAI API KEY , FUJI - CLI flags --model , --provider , etc. For architectural deep-dives, specs, and decision records, explore the docs/ /paradise-runner/fuji/blob/main/docs directory: — Architecture, module contracts, and data flow docs/core-spec.md — Core decisions and trade-offs docs/decisions.md — Architecture Decision Records docs/adr/