# Fuji: A minimal harness to deploy agents at scale

> Source: <https://github.com/paradise-runner/fuji>
> Published: 2026-08-19 13:00:24+00:00

`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/`