AI agents are stateless. Each session starts from scratch — decisions aren't remembered, work from other sessions is invisible, and context has to be re-explained every time.

JFL gives every project a shared brain. Context accumulates in git. Agents read past sessions, track eval scores, and propose improvements autonomously. Works with Claude Code, Pi, or any AI via MCP.

Quick Start

npm install -g jfl
jfl init -n my-project && cd my-project
claude  # or: jfl pi

That's it. Session hooks handle repo sync, branching, Context Hub startup, and auto-commit. You just work.

How It Works

You (or agent) works in a session
  → Journal captures decisions, features, fixes
    → Context Hub indexes everything (memory + semantic search)
      → Next session starts with full context automatically
        → Eval framework tracks agent performance
          → Self-driving loop proposes improvements
            → Auto-merge if eval scores improve

Everything lives in git — .jfl/journal/, .jfl/eval.jsonl, knowledge/ docs. No external database. Any AI can read it.

Core Concepts

| Concept | What It Is | How It Works | |---------|-----------|-------------| | Context Hub | Per-project daemon | Aggregates journals, knowledge, code into unified API. MCP + HTTP. | | Journal | Structured session log | JSONL entries: features, decisions, fixes, discoveries. Replay buffer for RL. | | Eval Framework | Agent scorecard | Composite scores, leaderboards, trajectories. Dual-writes up parent chain. | | Self-Driving Loop | Autonomous improvement | Detect issue → create fix → eval → auto-merge if improved. | | MAP Event Bus | Nervous system | Events flow between agents, services, and flows. SSE + WebSocket. | | Flow Engine | Declarative automation | YAML trigger-action flows: eval:scored → auto-merge, telemetry:insight → spawn fix. | | Pi Runtime | Multi-model TUI agent | JFL extension for Pi — full context injection, tools, custom rendering. | | Kanban | Task board | GitHub Issues-backed cards with Linear bidirectional sync. PP picks up and ships autonomously. |

Architecture

JFL supports three levels: Portfolio > GTM > Services.

my-portfolio/                  ← Coordinates multiple products
├── productrank-gtm/           ← Context layer for one product
│   ├── .jfl/                  ← Journal, eval, events, config
│   ├── knowledge/             ← VISION, ROADMAP, THESIS, NARRATIVE
│   ├── .claude/               ← Hooks, skills, agents
│   └── .mcp.json              ← MCP server config
│
└── my-api/                    ← Service repo (registered in GTM)
    └── .jfl/config.json       ← type: "service", gtm_parent

GTMs are context layers — they never house product code. Services register to GTMs and sync journals on session end.

CLI Reference

Daily Use

jfl status                    # Project status
jfl whoami                    # Current user, project, and root
jfl hud                       # Campaign dashboard
jfl synopsis [hours]          # Work summary
jfl ask "what did we decide?" # Search memory
jfl doctor                    # Health check
jfl doctor --json             # Machine-readable health output (for CI/evals)
jfl ide                       # Terminal workspace (tmux/cmux)

Context Hub

jfl context-hub ensure        # Start if not running
jfl context-hub dashboard     # Open web dashboard
jfl context-hub status        # Health check
jfl context-hub doctor        # Diagnose all projects

Agents & Eval

jfl eval list                 # Recent eval entries
jfl eval trajectory -a shadow # Score over time
jfl peter experiment          # Run autonomous improvement cycle
jfl predict run --proposal "Fix auth" --goal "improve tests"
jfl train policy-head         # Train RL policy head on journal data
jfl train status              # Training pipeline status

Kanban & Linear

jfl kanban ls                 # Task board
jfl kanban add "Fix the thing" # Add card
jfl kanban pick --agent cash  # Agent picks top card
jfl kanban bootstrap          # Create kanban labels in GitHub repo
jfl linear sync               # Bidirectional GitHub ↔ Linear sync
jfl linear sync --direction github  # Push GitHub state to Linear
jfl linear sync --direction linear  # Pull Linear into GitHub
jfl linear link               # Link repo to Linear project
jfl linear status             # Sync status and config

Services

jfl onboard /path/to/repo     # Register a service
jfl services                  # Interactive TUI
jfl services validate --fix   # Auto-repair config issues
jfl ci setup                  # Deploy eval + review CI workflows

Pi Runtime

jfl pi                        # Launch Pi with JFL extensions
jfl pi --model claude-opus-4-6 # Specific model
jfl pi agents run --team teams/gtm-team.yaml # Spawn agent team

MCP Tools

Available to Claude Code and any MCP client:

| Tool | Description | |------|------------| | context_get | Unified context (journal + knowledge + code) | | context_search | Semantic search across all sources | | memory_search | Search indexed memories by query + type | | memory_add | Add manual memory entry | | events_publish | Publish event to MAP bus | | events_recent | Recent events with pattern filter | | query_experiment_history | RL trajectories for agent experiments |

Self-Driving Loop

Agents detect issues, create fixes, and the system auto-merges if eval scores improve.

| Flow | Trigger | Action | |------|---------|--------| | Auto-merge | eval:scored (improved) | gh pr merge | | Flag regression | eval:scored (regressed) | Request changes on PR | | Fix blockers | review:findings (red) | Spawn agent to fix | | Cost spike | telemetry:insight (high) | Create fix PR | | Predict first | peter:pr-proposed | Stratus prediction gate |

CI closes the loop: jfl-eval.yml runs eval on PP pull requests. jfl-review.yml does AI code review. Both post events to Context Hub. jfl ci setup deploys both workflows to any repo.

Linear Integration

JFL syncs GitHub Issues ↔ Linear bidirectionally. When a PR is merged, the linked Linear issue moves to Done automatically.

jfl linear link               # Connect to your Linear workspace
jfl linear sync               # Full bidirectional sync
jfl linear sync --direction github --json  # CI-friendly output

The linear-sync GitHub Actions workflow runs on every issue event and on a 30-minute cron for drift correction. PP picks up Linear issues, creates PRs with cross-repo references (Closes org/repo#N), and the kanban moves them through backlog → in-progress → eval → done.

Dashboard

Pre-built Vite + Preact + Tailwind SPA served by Context Hub at /dashboard/.

Pages: Overview, Journal, Events, Services, Flows, Health, Agents, Experiments, Telemetry, Topology, Kanban

jfl context-hub dashboard     # Open in browser
jfl viz dash                  # Terminal equivalent

Configuration

All config in .jfl/config.json:

{
  "name": "my-project",
  "type": "gtm",
  "contextHub": { "port": 4360 },
  "registered_services": [],
  "context_scope": {
    "produces": ["eval:*", "journal:*"],
    "consumes": ["strategy:*"]
  }
}

Flows in .jfl/flows/self-driving.yaml. Knowledge in knowledge/. Skills in .claude/skills/.

Development

git clone https://github.com/402goose/jfl-cli
cd jfl-cli
npm install
npm run build
npm test          # 1270 tests
npm link          # Use local build globally

License

MIT