flanes 0.3.0

Fla: Feature Lanes for Agents - version control for agentic AI systems

Fla: Feature Lanes for Agents

Version Control for Agentic AI Systems

Version control designed from the ground up for AI agents. Replaces git's line-diff model with intent-based snapshots, physically isolated workspaces, and evaluation gating.

Why Fla?

Git assumes a single human making small, curated edits. AI agents break every part of that model.

	Git	Fla
Unit of work	Line diffs	Full world-state snapshots
Change metadata	Free-text commit message	Structured intent + agent identity
Quality gate	CI runs after merge	Evaluation gating before accept
Parallel agents	Branch conflicts	Physically isolated workspaces
Cost tracking	None	Per-transition token/API accounting

Quick Demo

cd my-project
fla init
# Writes files, then commits in one step:
fla commit --prompt "Add auth module" \
  --agent-id coder-1 --agent-type feature_dev --auto-accept

# Create isolated feature lane
fla lane create feature-auth

# Work in isolation, promote back to main
fla promote --workspace feature-auth --target main --auto-accept

# Query history
fla history --lane main

Or use the Python SDK:

from fla.agent_sdk import AgentSession

session = AgentSession(
    repo_path="./my-project",
    agent_id="coder-alpha",
    agent_type="feature_developer",
)

with session.work("Add authentication module", tags=["auth"], auto_accept=True) as w:
    (w.path / "auth.py").write_text("def authenticate(): ...")
    w.record_tokens(tokens_in=2000, tokens_out=1200)
# On exit: snapshots -> proposes -> accepts (or rejects on exception)

See examples/ for runnable demos.

Installation

pip install fla

# Optional: remote storage backends
pip install fla[s3]    # Amazon S3 (boto3)
pip install fla[gcs]   # Google Cloud Storage

Core Concepts

World States: Immutable snapshots of the entire project. Agents propose new world states, not diffs.

Intents: Structured metadata for every change: the instruction, who issued it, cost tracking, and semantic tags.

Transitions: Proposals to move from one state to another. Must be evaluated before acceptance.

Lanes: Isolated workstreams. Work is promoted into a target lane through evaluation, not merged.

Workspaces: Main workspace is the repo root (git-style). Feature lanes get physically isolated directories under .fla/workspaces/.

Architecture

+--------------------------------------------------+
|                 CLI / Agent SDK                    |
|       (fla commands / AgentSession API)            |
+--------------------------------------------------+
|                  Repository                        |
|   (propose, accept, promote, restore, etc)         |
+--------------------+-----------------------------+
|  WorkspaceManager  |     WorldStateManager        |
|  (isolation,       |  (states, transitions,        |
|   locking,         |   lanes, history, trace,      |
|   materialization) |   conflict detection)          |
+--------------------+-----------------------------+
|             Content-Addressed Store                |
|    (SHA-256 blobs + trees, dedup, integrity)       |
+--------------------------------------------------+
|                    SQLite                           |
|         (WAL mode, single-file database)           |
+--------------------------------------------------+

Key Features

• Git-style main: repo root IS the main workspace. Files stay where you expect them.
• Physical isolation: feature workspaces are real directories. Parallel agents can't stomp on each other.
• Smart incremental updates: workspace sync writes only changed files, not the entire tree.
• Cross-platform locking: atomic mkdir locking works on Linux, macOS, and Windows.
• Conflict detection: promote finds path-level collisions without content merging.
• Evaluators: run pytest, ruff, or custom checks as gates before accepting transitions.
• Cost tracking: per-transition token usage, wall time, and API call counts.
• Git bridge: fla export-git / fla import-git for CI integration.
• Remote storage: S3/GCS-backed sync for team collaboration.
• MCP server: expose Fla as tools for LLM integration via Model Context Protocol.
• REST API: fla serve starts a multi-threaded HTTP API.
• Garbage collection: fla gc removes rejected states and unreachable objects.

Documentation

• User Guide: comprehensive reference for all features
• Examples: runnable demo scripts
• Contributing: development setup and guidelines

Workspace Layout

my-project/
+-- .fla/
|   +-- config.json
|   +-- store.db                        # SQLite database
|   +-- main.json                       # main workspace metadata
|   +-- workspaces/
|       +-- feature-auth/               # isolated feature workspace
|       +-- feature-auth.json
+-- app.py                              # YOUR FILES AT REPO ROOT
+-- lib/

Running Tests

pip install -e ".[dev]"
python -X utf8 -m pytest tests/ -v

License

MIT