Fuji: A minimal harness to deploy agents at scale

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:

export ANTHROPIC_API_KEY="your-anthropic-key"

export OPENAI_API_KEY="your-openai-key"

Run fuji

in one-shot mode:

fuji run --prompt "Fix failing tests in pkg/session"

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:

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

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 error2

: Runtime failure3

: 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/ directory:

— Architecture, module contracts, and data flowdocs/core-spec.md

— Core decisions and trade-offsdocs/decisions.md

— Architecture Decision Recordsdocs/adr/

source & further reading

github.com — original article herd-debate: equal Claude vs Codex design peers in Herdr Show HN: Cairn – self-hosted Shape Up tool with a code-aware PM agent SIL: A semantic interface layer for web applications and AI agents