Local-only multi-agent orchestration, knowledge graph, and task management for software projects.
Filament gives AI coding agents (and humans) a shared project brain — a knowledge graph of tasks, modules, services, plans, and docs with dependency tracking, file reservations, inter-agent messaging, and a real-time TUI dashboard. Everything runs locally with a SQLite database per project.
- Knowledge graph — entities (tasks, modules, services, agents, plans, docs, lessons) connected by typed relations (blocks, depends_on, produces, owns, relates_to, assigned_to)
- Task management — priority-ranked ready queues, critical path analysis, dependency tracking, impact scoring
- Lesson capture — structured knowledge capture of gotchas, solutions, and recurring patterns with problem/solution/learned fields
- Full-text search — FTS5-powered search across all entities with BM25 relevance ranking
- Multi-agent orchestration — dispatch AI agents with specialized roles (coder, reviewer, planner, dockeeper), monitor runs, handle agent death gracefully
- Inter-agent messaging — targeted message passing between agents with typed messages (text, question, blocker, artifact)
- Advisory file reservations — TTL-based file locks to coordinate concurrent edits across agents
- Graph analytics — PageRank and degree centrality to identify high-impact entities and bottlenecks
- MCP server — 16-tool Model Context Protocol interface for AI agent integration
- TUI dashboard — real-time terminal UI showing tasks, agent runs, and reservations
- Hybrid architecture — direct SQLite for single-user, Unix socket daemon for multi-agent
- Project config — layered
fl.tomlconfiguration with environment variable overrides - Real-time watch — live event stream from the daemon for monitoring agent activity
- Git integration — pre-commit hooks for reservation conflict checks, audit snapshots to git branches
- Seed command — bootstrap the knowledge graph from existing CLAUDE.md documentation
macOS or Linux required (uses Unix sockets for daemon mode). SQLite is bundled — no system install needed.
curl -fsSL https://raw.githubusercontent.com/JYC11/filament/main/install.sh | shOptions:
# Custom install directory
curl -fsSL https://raw.githubusercontent.com/JYC11/filament/main/install.sh | sh -s -- --to /usr/local/bin
# Specific version
curl -fsSL https://raw.githubusercontent.com/JYC11/filament/main/install.sh | sh -s -- --version v1.0.0Requires the Rust toolchain (stable channel).
git clone https://github.com/JYC11/filament.git
cd filament
make build CRATE=all RELEASE=1
make install # installs to ~/.local/bin (default)
make install DEST=/usr/local/bin # custom destinationmake uninstall # removes from ~/.local/bin (default)
make uninstall DEST=/usr/local/bin # custom destinationmake build CRATE=all # debug build
make test CRATE=all # run all tests
make ci # full CI: fmt check + clippy + testsReady-to-use Claude Code skills are included in skills/. Copy them to your skills directory:
cp -r skills/filament ~/.claude/skills/filament
cp -r skills/filament-bug-report-format ~/.claude/skills/filament-bug-report-format| Skill | Purpose |
|---|---|
filament |
Complete CLI reference, entity types, relation types, workflow patterns, and agent preamble for multi-agent dispatch. Loaded automatically when relevant. |
filament-bug-report-format |
Creates an anonymized snapshot of your .fl/fl.db database with structured reproduction steps for filing bug reports. Strips user-identifiable content while preserving schema, entity structure, and relations. Say "report a bug" to activate. |
For non-Claude-Code agents, create a skill or rule from this README so your agent can use fl commands natively:
Create a skill for the filament CLI based on the README at:
https://github.com/JYC11/filament/blob/main/README.md
For multiple Claude instances working concurrently on the same project, use tmux to launch parallel claude -p sessions. Start the daemon (fl serve), then give each agent its own tmux window. Filament coordinates them through file reservations, task dependencies, and inter-agent messaging. See Agent Dispatching and the skill's references/agent-preamble.md for the full workflow.
Create a .fl/ directory with a SQLite database in your project root:
cd your-project
fl initThis creates:
.fl/fl.db— SQLite database (WAL mode).fl/content/— content file storage
Add .fl/ to your .gitignore.
Every command supports these flags:
| Flag | Short | Description |
|---|---|---|
--json |
Output JSON instead of human-readable text | |
--verbose |
-v |
Increase verbosity (-v debug, -vv trace) |
--quiet |
-q |
Suppress non-error output |
Filament's core data model is a knowledge graph of entities connected by relations. Every entity has a unique 8-character slug (e.g., a3kf92mx) for human-friendly identification.
| Type | Purpose | Lifecycle | Example |
|---|---|---|---|
task |
Work items — the only type with full status workflow. Has priority, dependency tracking, ready-queue ranking, critical path, and impact scoring. | open → in_progress → closed (or blocked) |
"Implement login endpoint", "Fix bug #42" |
module |
Code structure — crates, files, subsystems. Relate to tasks with owns or relates_to so agents know which code areas a task touches. |
Structural (no workflow) | "filament-core", "auth module", "store.rs" |
service |
Runtime components — running infrastructure, external dependencies. Distinguishes what runs from what's code. | Structural (no workflow) | "sqlite-db", "unix-socket-server", "redis-cache" |
agent |
Actors — AI agents or human operators. Required for task assign, message send, reserve. The dispatch system tracks who's working on what. |
Structural (no workflow) | "planner-agent", "code-reviewer", "alice" |
plan |
Planning documents — group tasks via owns relations. Always use --content to point at the actual .md file. The entity summary is a 1-2 sentence description; the file is the source of truth. |
Structural (no workflow) | "phase-3-plan", "architecture-overview" |
doc |
Reference material — ADRs, specs, runbooks, knowledge. Like plans, always use --content to reference the file on disk. The graph adds queryable structure; the file has the content. |
Structural (no workflow) | "adr-003-unified-graph", "api-spec", "gotchas" |
lesson |
Knowledge capture — gotchas, solutions, recurring patterns. Structured fields: problem, solution, learned, optional pattern. Use fl lesson add to create. Searchable via FTS5. |
Structural (no workflow) | "SQLite CHECK constraint gotcha", "N+1 query fix" |
Design principle: The graph is lightweight. Entities store short summaries + pointers to files. For doc and plan types, always use --content path/to/file.md so the physical file remains the source of truth. The graph adds queryable relations, dependency tracking, and context queries on top.
All entities have a status field (open, in_progress, closed, blocked), but only tasks use the full status workflow. Other entity types are structural — they exist to give the graph shape for context queries, not to be "completed".
fl add "Authentication Module" --type module --summary "Handles JWT auth" --priority 1
# With key facts (JSON object)
fl add "API Gateway" --type service \
--summary "Routes requests to microservices" \
--facts '{"port": 8080, "protocol": "HTTP/2"}'
# With a content file (must exist on disk)
fl add "Architecture Decision" --type doc \
--summary "ADR-001: Database choice" \
--content .plan/adr/001-database.mdOutput: Created: a3kf92mx (550e8400-e29b-41d4-a716-446655440000)
fl inspect a3kf92mxShows name, slug, ID, type, status, priority, summary, facts, content path, relations, and timestamps.
fl update a3kf92mx --status in_progress
fl update a3kf92mx --summary "Updated description"
fl update a3kf92mx --status closed --summary "Done"
fl update a3kf92mx --priority 0
fl update a3kf92mx --facts '{"key": "value"}'
fl update a3kf92mx --content path/to/file.mdPrint the raw content file associated with an entity:
fl read a3kf92mxfl list # all entities
fl list --type task # only tasks
fl list --status open # only open entities
fl list --status all # all statuses (including closed)
fl list --type module --status in_progressfl remove a3kf92mxRemoves the entity and all its relations.
Connect entities with typed, directed edges.
| Type | Meaning |
|---|---|
blocks |
Source blocks target from starting |
depends_on |
Source depends on target being done |
produces |
Source produces/creates target |
owns |
Source owns/contains target |
relates_to |
General association |
assigned_to |
Agent is assigned to a task |
fl relate abc12345 blocks def67890
fl relate abc12345 depends_on def67890 --summary "needs API first"
fl relate abc12345 owns def67890 --weight 1.0fl unrelate abc12345 blocks def67890View the neighborhood around an entity (BFS traversal):
fl context --around abc12345 # default depth 2, limit 20
fl context --around abc12345 --depth 3 # deeper traversal
fl context --around abc12345 --limit 50 # more resultsTasks are the primary work unit. The task subcommand provides specialized task operations beyond basic entity CRUD.
fl task add "Implement login endpoint" --summary "POST /auth/login" --priority 0
# With dependency relations
fl task add "Write integration tests" \
--summary "Test the login flow" \
--depends-on abc12345 \
--priority 2
# With blocking relation
fl task add "Deploy to staging" --blocks def67890fl task list # open tasks (default)
fl task list --status all # all tasks regardless of status
fl task list --status in_progress
fl task list --status closed
fl task list --unblocked # only tasks with no blockersNote: --status and --unblocked are mutually exclusive.
fl task show abc12345Show unblocked tasks ranked by priority and impact score:
fl task ready # top 20 by default
fl task ready --limit 5 # top 5 onlyImpact score counts how many downstream tasks are transitively blocked by each task — higher impact tasks should be done first.
Show the longest dependency chain blocking a task:
fl task blocker-depth abc12345fl task close abc12345fl task assign abc12345 --to agent_slugCreates an assigned_to relation from the agent to the task.
Structured knowledge capture for gotchas, solutions, and recurring patterns. Each lesson has four fields stored in the entity's key_facts JSON.
fl lesson add "SQLite CHECK constraint gotcha" \
--problem "Cannot ALTER TABLE to modify CHECK constraints" \
--solution "Recreate the table with the new constraint, copy data, drop old" \
--learned "SQLite CHECK constraints are immutable after table creation" \
--pattern "schema-migration-gotcha"fl lesson list # all lessons
fl lesson list --pattern "migration" # filter by pattern name
fl lesson list --status open # filter by statusfl lesson show abc12345Displays the structured problem/solution/learned/pattern fields.
fl lesson delete abc12345Full-text search across all entities using SQLite FTS5 with BM25 relevance ranking. Searches entity names, summaries, and key_facts.
fl search "migration" # search all entities
fl search "connection pool" --type lesson # filter by entity type
fl search "deployment" --limit 5 # limit resultsSupports FTS5 query syntax: words, phrases ("like this"), OR, NOT.
Agents communicate through targeted messages. No broadcast — every message has a sender and recipient.
| Type | Purpose |
|---|---|
text |
General communication (default) |
question |
Questions needing answers |
blocker |
Blocking issues that need resolution |
artifact |
Deliverables, code snippets, results |
fl message send --from coder-1 --to reviewer-1 \
--body "Login endpoint ready for review"
fl message send --from reviewer-1 --to coder-1 \
--body "Missing input validation on email field" \
--type blockerfl message inbox coder-1Shows unread messages with sender, type, and a preview.
fl message read <message-uuid>Returns an error if the message was already read (distinct from not found).
Advisory file locks to coordinate concurrent edits. Reservations use glob patterns and have a TTL.
# Shared reservation (default) — multiple agents can hold shared locks
fl reserve "src/auth/*.rs" --agent coder-1 --ttl 1800
# Exclusive reservation — only one agent can hold this lock
fl reserve "src/main.rs" --agent coder-1 --exclusive --ttl 3600Default TTL is 3600 seconds (1 hour).
fl release "src/auth/*.rs" --agent coder-1fl reservations # all active reservations
fl reservations --agent coder-1 # filter by agent
fl reservations --clean # clean expired, then listFilament runs in two modes:
- Direct mode — CLI talks directly to SQLite (single-user, default)
- Daemon mode — CLI connects to a Unix socket server (multi-agent, required for dispatching)
The CLI auto-detects which mode to use based on whether .fl/fl.sock exists.
fl serve # background (daemonizes)
fl serve --foreground # foreground (for debugging)fl stopfl serve --socket-path /tmp/fl.sockDispatch AI agents to work on tasks. Requires the daemon to be running.
| Role | Purpose | Key Capabilities |
|---|---|---|
coder |
Implement code changes | File reservations, code editing, test running |
reviewer |
Review code for correctness and quality | Entity inspection, sending feedback messages |
planner |
Break down work and create plans | Entity/relation creation, dependency analysis, critical path |
dockeeper |
Maintain documentation | Entity updates, file reservations for docs |
Each role has a compiled-in system prompt and a whitelist of MCP tools it can use.
fl agent dispatch abc12345 # default role: coder
fl agent dispatch abc12345 --role reviewer
fl agent dispatch abc12345 --role plannerfl agent dispatch-all # up to 3 parallel, coder role
fl agent dispatch-all --max-parallel 5 --role reviewerThis finds all unblocked tasks and dispatches agents sequentially (one RPC per task) up to the parallel limit. Requires daemon mode.
fl agent status <run-uuid> # check a specific run
fl agent list # list running agents
fl agent history abc12345 # all runs for a task- Agent is spawned as a subprocess with the task context and role prompt
- Agent uses MCP tools to interact with the knowledge graph
- Agent emits a structured
AgentResultJSON on completion - Filament parses the result, routes messages, and updates task status
- On agent death: task status is reverted, file reservations are released, graph is refreshed
- Timeout: agents are killed after
agent_timeout_secs(default 1 hour, 0 = no limit) - Reconciliation: daemon periodically checks for dead agent PIDs and cleans up orphaned runs
Filament exposes a Model Context Protocol server for AI agent integration. The MCP server provides 16 tools over JSON-RPC via stdin/stdout.
fl mcpThis runs the MCP stdio transport. All logs go to stderr; stdout is reserved for JSON-RPC.
| Tool | Description |
|---|---|
fl_add |
Create a new entity |
fl_inspect |
Get entity details and relations |
fl_update |
Update entity summary and/or status |
fl_delete |
Delete an entity and its relations |
fl_list |
List/filter entities by type and status |
| Tool | Description |
|---|---|
fl_relate |
Create a relation between entities |
fl_unrelate |
Remove a relation |
fl_context |
BFS graph neighborhood query |
| Tool | Description |
|---|---|
fl_task_ready |
Get ranked unblocked tasks |
fl_task_close |
Mark a task as closed |
| Tool | Description |
|---|---|
fl_message_send |
Send a message to another agent |
fl_message_inbox |
Check unread messages |
fl_message_read |
Mark a message as read |
| Tool | Description |
|---|---|
fl_reserve |
Acquire an advisory file lock |
fl_release |
Release a file reservation |
fl_reservations |
List active reservations |
An interactive terminal UI for monitoring the knowledge graph in real time.
fl tui| Tab | Key | Content |
|---|---|---|
| Entities | 1 |
Unified entity table with multi-select type/status filtering |
| Agents | 2 |
Running agent processes with role, PID, duration |
| Reservations | 3 |
Active file locks with TTL countdown |
| Messages | 4 |
Messages with kind, agent, and body |
| Config | 5 |
Read-only view of resolved fl.toml configuration values |
| Analytics | 6 |
PageRank scores and degree centrality for graph entities |
| Key | Action |
|---|---|
q / Ctrl+C |
Quit |
Tab |
Next tab |
Shift+Tab |
Previous tab |
1–6 |
Jump to tab |
j / Down |
Move selection down |
k / Up |
Move selection up |
Enter |
Open detail pane (60/40 split with events + critical path) |
Esc |
Close detail pane |
n / p |
Next / previous page (Entities tab) |
t |
Cycle type filter (Entities tab) |
s |
Cycle status filter (Entities tab) |
h |
Toggle agent history (Agents tab) |
r |
Force refresh + health check |
- Entities: client-side paging (20 per page), multi-select type/status filters, detail pane with event log and critical path on Enter.
- Agents: shows live duration for running agents. Press
hto toggle between running-only and full history. Status colors: green=running, cyan=completed, red=failed, yellow=blocked, magenta=needs_input. - Reservations: TTL countdown with yellow warning under 5 minutes and red "EXPIRED" label. Expired rows are dimmed.
- Messages: escalations color-coded by kind (red=blocker, yellow=question, magenta=needs_input).
- Config: read-only display of resolved configuration values.
- Analytics: PageRank and degree centrality scores, calculated on demand.
Auto-refreshes every 5 seconds. Status bar shows entity count, connection mode (daemon/direct), health indicator, and last refresh time.
Export the entire knowledge graph (entities, relations, messages, events) as JSON for backup or transfer between projects.
fl export # print to stdout
fl export --output backup.json # write to file
fl export --no-events # exclude event logfl import --input backup.json # read from file
cat backup.json | fl import # read from stdin
fl import --input backup.json --no-events # skip eventsImport reports counts of entities, relations, messages, and events imported.
View pending escalations — blockers, questions, and needs-input statuses from agent runs that require human attention.
fl escalations # human-readable table
fl escalations --json # structured JSONOutput shows kind, agent name, message body, and associated task (if any).
When FILAMENT_AUTO_DISPATCH=1 is set, the daemon automatically dispatches agents to newly-unblocked tasks. When an agent closes a task, any downstream tasks that become unblocked are queued for dispatch.
FILAMENT_AUTO_DISPATCH=1 fl serveGenerate shell completions for your preferred shell:
fl completions bash > ~/.local/share/bash-completion/completions/fl
fl completions zsh > ~/.zfunc/_fl
fl completions fish > ~/.config/fish/completions/fl.fishSupported shells: bash, zsh, fish, elvish, powershell.
Filament uses a layered config system. Create .fl/config.toml in your project:
fl config init > .fl/config.toml # generate template
fl config show # show resolved values
fl config path # show config file pathResolution order: environment variables (FILAMENT_*) > config file > defaults.
| Setting | Env Var | Default |
|---|---|---|
default_priority |
— | 2 |
output_format |
— | text |
agent_command |
FILAMENT_AGENT_COMMAND |
claude |
auto_dispatch |
FILAMENT_AUTO_DISPATCH |
false |
context_depth |
FILAMENT_CONTEXT_DEPTH |
2 |
max_auto_dispatch |
FILAMENT_MAX_AUTO_DISPATCH |
3 |
cleanup_interval_secs |
FILAMENT_CLEANUP_INTERVAL |
60 |
idle_timeout_secs |
FILAMENT_IDLE_TIMEOUT |
1800 (0 = never, daemon only) |
reconciliation_interval_secs |
FILAMENT_RECONCILIATION_INTERVAL |
30 (daemon only) |
agent_timeout_secs |
FILAMENT_AGENT_TIMEOUT |
3600 (0 = no limit, daemon only) |
Real-time event stream from the daemon. Requires fl serve to be running.
fl watch # all events
fl watch --events entity_created,status_change # filter by typeIdentify the most connected/important entities in the knowledge graph:
fl pagerank # top 20 by PageRank score
fl pagerank --damping 0.85 --iterations 50 --limit 10Show entities with the most connections:
fl degree # top 20 by total degree
fl degree --limit 10Pre-commit hook that blocks commits when staged files conflict with exclusive file reservations held by other agents.
fl hook install # add to .git/hooks/pre-commit
fl hook uninstall # remove from pre-commit
fl hook check # run the check manually
fl hook check --agent coder-1 # exclude own reservationsBootstrap the knowledge graph from markdown documentation:
fl seed --file CLAUDE.md # parse a specific markdown file
fl seed --files paths.txt # ingest multiple files listed one per line
fl seed --file CLAUDE.md --dry-run # preview without creatingParses ## Section headings as Doc entities with summaries from the first content line. Skips duplicates.
The --files flag accepts a text file with one markdown path per line (blank lines and # comments are skipped). Combine with --dry-run to preview before ingesting.
Snapshot the knowledge graph to a git branch for version-controlled audit trails:
fl audit # commit to filament-audit branch
fl audit --branch my-audit # custom branch name
fl audit --message "milestone snapshot" # custom commit messageExports entities, relations, messages, and events as JSON. Creates an orphan branch on first run.
All commands support --json for machine-readable output. Errors are also structured:
{
"code": "entity_not_found",
"message": "No entity with slug 'xyz'",
"hint": "Check the slug with 'fl list'",
"retryable": false
}filament/
├── Cargo.toml # workspace: 4 crates, single binary
├── Makefile # build, test, lint, CI targets
├── migrations/ # SQLite migrations (sqlx)
├── crates/
│ ├── filament-core/ # library: models, graph, storage, errors
│ ├── filament-cli/ # binary: clap CLI, command handlers
│ ├── filament-daemon/ # library: Unix socket server, MCP, agent roles
│ └── filament-tui/ # library: ratatui terminal UI
└── .plan/ # plans, ADRs, test standards
make fmt CRATE=all # format code
make fmt CRATE=all CHECK=1 # check formatting (CI)
make check CRATE=all CLIPPY=1 # clippy lints
make test CRATE=all # run all tests
make test CRATE=filament-core # test a single crate
make ci # full CI pipeline
make migration NAME=add_foo # create a new migration
make adr TITLE="Decision name" # create a new ADRA filament is a single fine thread that, woven together with others, forms something strong. In the same way, Filament weaves together isolated pieces of project knowledge — tasks, code modules, plans, docs, lessons, agent activity — into a connected graph that's stronger than the sum of its parts. The name also nods to the thin conductive wire in a light bulb: the thing that turns energy into light. Filament turns scattered context into clarity.
Filament was directly inspired by beads_rust (task management and error patterns) and Flywheel (multi-agent orchestration ecosystem), both by Jeff Emanuel. Those projects demonstrated powerful ideas across separate tools — Filament consolidates them into a single Rust binary that handles knowledge graph, task management, agent orchestration, messaging, and file coordination all in one place.
The lessons feature — structured knowledge capture of gotchas, solutions, and recurring patterns — was inspired by runes.
MIT License. See LICENSE for details.