Skip to main content
Agents are configured with TOML files in .jfl/agents/. Each file defines one agent with its metric, eval script, scope, and constraints.

​
Basic Example

.jfl/agents/test-coverage.toml
[agent]
name = "test-coverage"
scope = "tests"
metric = "coverage_percent"
direction = "maximize"
time_budget_seconds = 600
rounds = 10
target_repo = "../my-service"
description = "Add tests for uncovered files. Focus on src/ files with 0% coverage first."

[eval]
script = "eval/test-coverage.sh"
data = "eval/fixtures/test-coverage-baseline.jsonl"

[constraints]
scope_files = ["src/**/*.ts", "src/**/__tests__/*.test.ts"]
max_file_changes = 5

​
Reference

​
[agent] Section

FieldTypeRequiredDescription
namestring✅Unique agent identifier
scopestring✅Category (tests, quality, performance, product)
metricstring✅Primary metric name (must match eval script output)
directionstring✅"maximize" or "minimize"
time_budget_secondsnumber✅Max time per round
roundsnumberDefault rounds per session (overridable via CLI)
target_repostringRelative path to target repo (for cross-repo agents)
descriptionstringInstructions for the agent — what to do, what to avoid

​
[eval] Section

FieldTypeRequiredDescription
scriptstring✅Path to eval script (relative to project root)
datastring✅Path to eval fixtures/baseline data

​
[constraints] Section

FieldTypeDescription
scope_filesstring[]Glob patterns for files the agent can modify
files_in_scopestring[]Additional file patterns (broader scope)
files_readonlystring[]Files the agent must NOT modify
max_file_changesnumberMaximum files changed per round

​
[policy] Section (Advanced)

FieldTypeDefaultDescription
embedding_modelstringautoModel for state embeddings
exploration_ratenumber0.2Initial exploration rate (ε-greedy)
decay_per_roundnumber0.004Exploration decay per round
min_explorationnumber0.05Minimum exploration rate

​
[context_scope] Section

FieldTypeDescription
producesstring[]Events this agent emits (e.g., "perf:cli-improved")
consumesstring[]Events this agent reacts to (e.g., "telemetry:metric-alert")

​
Full Example (CLI Speed Agent)

.jfl/agents/jfl-cli-speed.toml
[agent]
name = "jfl-cli-speed"
scope = "performance"
metric = "p90_ms"
direction = "minimize"
time_budget_seconds = 180
rounds = 50
target_repo = "../jfl-cli"

[eval]
script = "eval/cli-speed.sh"
data = "eval/fixtures/cli-speed-baseline.jsonl"

[constraints]
scope_files = [
    "src/index.ts",
    "src/commands/status.ts",
    "src/commands/doctor.ts",
    "src/lib/service-detector.ts",
    "src/utils/cache.ts",
]
files_in_scope = ["src/commands/**/*.ts", "src/lib/**/*.ts"]
files_readonly = ["eval/**", "node_modules/**", "dist/**"]
max_file_changes = 3

[policy]
exploration_rate = 0.2
decay_per_round = 0.004
min_exploration = 0.05

[context_scope]
produces = ["perf:cli-improved", "perf:latency-reduced"]
consumes = ["telemetry:metric-alert", "code:refactored"]

​
Creating an Agent Interactively

jfl peter agent create
This walks you through setting up name, metric, eval script, and scope.

​
Listing Agents

jfl peter agent list

  Configured Agents

  test-coverage
    Scope: tests
    Metric: coverage_percent (maximize)
    Time budget: 600s
    Files: src/**/*.ts, src/**/__tests__/*.test.ts

  cli-speed
    Scope: performance
    Metric: p90_ms (minimize)
    Time budget: 180s
    Files: src/index.ts, src/commands/status.ts, ...

​
Archiving Agents

Move dead agents to .jfl/agents/_archived/: 
mv .jfl/agents/old-agent.toml .jfl/agents/_archived/
Archived agents are ignored by the nightly loop and agent list.