fuji

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.

---

Key Features

• 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.

---

Quick Start

1. Installation

Build the static binary:

go build -o fuji ./cmd/fuji

2. Set Up Credentials

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"

3. Run a Task

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

---

Scheduling Jobs with Cron

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.

---

CLI Reference

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)

Exit Codes

• 0: Success (task completed normally)
• 1: Configuration or authentication error
• 2: Runtime failure
• 3: Aborted (SIGINT / cancellation)

---

Bundled Tools

fuji guarantees the following standard tools across all environments:

---

Go Library Usage

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)
	}
}

---

Configuration Hierarchy

fuji merges configuration in order of increasing precedence:

1. Defaults
2. User config (~/.fuji/config.json)
3. Project config (<cwd>/.fuji/config.json)
4. Environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, FUJI_*)
5. CLI flags (--model, --provider, etc.)

---

Documentation

For architectural deep-dives, specs, and decision records, explore the docs/ directory:

• docs/core-spec.md — Architecture, module contracts, and data flow
• docs/decisions.md — Core decisions and trade-offs
• docs/adr/ — Architecture Decision Records

fuji