Minimal Bun + TypeScript coding agent with an autonomous 8-hour self-evolution harness.

• LLM-driven coding agent (OpenAI) with tool calling.
• OpenAI integration uses the Responses API (/v1/responses) for codex-compatible models.
• Tooling for URL fetch, Perplexity web search, Hacker News signals, workspace file ops, and Sprites remote build execution.
• Skill loader for .agents/skills/**/SKILL.md.
• Autonomous evolve cycle that:
  1. observes (issues, commits, journal, optional HN),
  2. orients,
  3. chooses one bounded high-impact change,
  4. implements + validates,
  5. commits if green,
  6. reverts if red,
  7. journals outcome.

Detailed schema for JOURNAL.md entries and the process for evolving it are recorded in docs/journal-schema.md so future cycles can emit and validate entries consistently.

• Bun >=1.3
• Git + GitHub CLI (gh) authenticated
• OpenAI API key
• Optional: Perplexity API key
• Optional: Sprites CLI for compile-heavy remote runs

bun install

Create env file (or export variables):

export OPENAI_API_KEY=...
export OPENAI_MODEL=gpt-5.1-codex-mini
export PERPLEXITY_API_KEY=...            # optional, enables web_search tool
export SPRITES_ENABLED=false             # set true to enable Sprites policy
export SPRITES_DEFAULT_NAME=qbuild

# Run agent
bun run agent -- "test task: summarize repository architecture"

# Run evolve cycle (plan only)
bun run evolve:cycle --dry-run

# Run evolve cycle (real)
bun run evolve:cycle

# Lint / tests
bun run lint
bun test

# check CLI
sprite --help

# wrapper examples
.agents/skills/sprites/scripts/sprites.sh create qbuild
.agents/skills/sprites/scripts/sprites.sh exec qbuild "bash -lc 'uname -a'"
.agents/skills/sprites/scripts/sprites.sh api-get qbuild "/workspace/README.md"
.agents/skills/sprites/scripts/sprites.sh destroy qbuild

# ephemeral build workflow
.agents/skills/sprites/scripts/sprites.sh ephemeral qbuild "bun run lint && bun test"

If Sprites is unavailable and SPRITES_ENABLED=true, fractal fails safely with actionable setup errors.

Loaded from .agents/skills/**/SKILL.md:

• hackernews
• web-search
• sprites
• dialectic

• Files:
  • .github/workflows/evolve.yml direct task-runner entrypoint
  • .github/workflows/evolve-task.yml reusable task workflow
  • .github/workflows/evolve-meta.yml outer orchestrator that fans out candidate goals and promotes the best bundle
• Triggers:
  • schedule: every 8 hours (0 */8 * * *)
  • workflow_dispatch: manual run
• Permissions:
  • contents: write
  • issues: write
  • pull-requests: write
• Uses:
  • OPENAI_API_KEY (required)
  • PERPLEXITY_API_KEY (optional)
  • SPRITE_TOKEN (required only when SPRITES_ENABLED=true)

Workflow behavior:

• evolve.yml delegates to the reusable task workflow with a single canonical goal.
• evolve-task.yml runs bun run evolve:cycle, persists JOURNAL.md, packages a candidate bundle, and optionally pushes.
• evolve-meta.yml is the split-loop orchestrator: dispatch it manually to fan out a few goal variants, download candidate bundles, score them from traces, reapplies the best patch on a fresh checkout, validates, and opens a PR.
• Explicit plan outcomes remain non-error even when they produce no diff.
• High-uncertainty cases are recorded as planned handoffs, not a separate outcome.
• Implement runs that produce no diff still fail; only explicit planned handoffs are green.
• Candidate bundles include a patch, summary JSON, and logs under the candidate artifact name.

Set these repository settings:

# required when using sprites
gh secret set SPRITE_TOKEN --repo ghillb/fractal

# enable sprites policy in evolve
gh variable set SPRITES_ENABLED --body \"true\" --repo ghillb/fractal
gh variable set SPRITES_DEFAULT_NAME --body \"qbuild\" --repo ghillb/fractal

The workflow installs Sprite CLI, runs sprite auth setup --token "$SPRITE_TOKEN", then enables compile-heavy remote checks.

$ bun run agent -- "test task: summarize repository architecture"
fractal is organized into src/agent (LLM loop), src/tools (tool adapters), src/skills (SKILL loader), and src/evolve (autonomous cycle).

$ bun run evolve:cycle --dry-run
{
  "mode": "dry-run",
  "goal": "Become an entity that is ever more capable while improving safely.",
  "decision": {
    "diagnosis": "...",
    "chosenChange": "...",
    "rationale": "...",
    "uncertainty": 0.32,
    "executionMode": "implement",
    "compileHeavy": false,
    "targetFiles": ["src/evolve/journal.ts"],
    "nextCyclePlan": [],
    "followUps": ["..."]
  }
}

When SPRITES_ENABLED=true and change is compile-heavy, evolve enforces remote validation:

- chosen_change: add Rust build check
- compile_heavy: true
- action: .agents/skills/sprites/scripts/sprites.sh ephemeral qbuild "bun run lint && bun test"
- result: pass -> commit evolve(agent): ...