{"id":50929971,"url":"https://github.com/foundryside-dev/filigree","last_synced_at":"2026-06-17T03:04:48.584Z","repository":{"id":338789636,"uuid":"1158331537","full_name":"foundryside-dev/filigree","owner":"foundryside-dev","description":"Agent-native issue tracker with convention-based project discovery","archived":false,"fork":false,"pushed_at":"2026-06-15T08:56:06.000Z","size":18256,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T11:37:25.255Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/foundryside-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-15T07:12:31.000Z","updated_at":"2026-06-06T20:42:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"24f435f3-9d93-41b1-9b24-62948cdf32a7","html_url":"https://github.com/foundryside-dev/filigree","commit_stats":null,"previous_names":["tachyon-beep/filigree","foundryside-dev/filigree"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/foundryside-dev/filigree","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Ffiligree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Ffiligree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Ffiligree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Ffiligree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foundryside-dev","download_url":"https://codeload.github.com/foundryside-dev/filigree/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Ffiligree/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34431810,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-17T03:04:47.947Z","updated_at":"2026-06-17T03:04:48.574Z","avatar_url":"https://github.com/foundryside-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Filigree\n\nLocal-first issue tracker designed for AI coding agents — SQLite, MCP tools, no cloud, no accounts.\n\n[![CI](https://github.com/foundryside-dev/filigree/actions/workflows/ci.yml/badge.svg)](https://github.com/foundryside-dev/filigree/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/filigree)](https://pypi.org/project/filigree/)\n[![Python 3.11+](https://img.shields.io/pypi/pyversions/filigree)](https://pypi.org/project/filigree/)\n[![License: MIT](https://img.shields.io/pypi/l/filigree)](https://github.com/foundryside-dev/filigree/blob/main/LICENSE)\n\n## What Is Filigree?\n\nFiligree is a lightweight, SQLite-backed issue tracker designed for AI coding agents (Claude Code, Codex, etc.) to use as first-class citizens. It exposes 118 MCP tools so agents interact natively, plus a full CLI for humans and background subagents.\n\nTraditional issue trackers are human-first — agents scrape CLI output or parse API responses. Filigree flips this: agents get a pre-computed `context.md` at session start, claim work with optimistic locking, and resume sessions via event streams without re-reading history. For Claude Code, `filigree install` wires up session hooks and a workflow skill pack so agents get project context automatically.\n\nFiligree is local-first. No cloud, no accounts. Each project gets a `.weft/filigree/` directory (like `.git/`) containing a SQLite database, configuration, and auto-generated context summary; legacy `.filigree/` stores keep working and migrate on the next `filigree init`. Installations support two modes: `ethereal` (default, per-project) and `server` (persistent multi-project daemon). A named Weft HTTP generation at `/api/weft/*` serves federation-aware integrations while the classic HTTP surface stays supported for existing callers.\n\nFiligree is the work-state member of the **Weft federation** — a family of independently-useful code-governance tools woven together by narrow, additive contracts. Filigree runs fully standalone; the Weft surface is optional enrichment. The authoritative federation roster, axiom, and composition doctrine live at the Weft hub (`~/weft`, see `~/weft/doctrine.md`); Filigree owns its own HTTP/MCP/CLI surface and contracts (see [docs/federation/contracts.md](docs/federation/contracts.md)).\n\n**Security boundary:** Filigree does not encrypt, sandbox, harden, or secure stored project data beyond ordinary filesystem permissions and standard HTTPS transport if you put it behind HTTPS yourself. Do not use Filigree for secure, regulated, confidential, or business-sensitive data.\n\n### Key Features\n\n- **MCP server** with 118 tools — agents interact natively without parsing text\n- **Full CLI** with `--json` output for background subagents and `--actor` for audit trails\n- **Weft HTTP generation** — stable `/api/weft/*` contracts with classic compatibility for existing integrations\n- **Claude Code integration** — session hooks inject project snapshots at startup; bundled skill pack teaches agents workflow patterns\n- **Workflow templates** — 24 issue types across 9 packs with enforced state machines\n- **Dependency graph** — blockers, ready-queue, critical path analysis\n- **Hierarchical planning** — milestone/phase/step hierarchies with automatic unblocking\n- **Atomic claiming** — optimistic locking prevents double-work in multi-agent scenarios\n- **Agent handoff tools** — claim leases, stale-claim discovery, observation triage, shared file annotations, and scanner/finding workflows\n- **Bundled scanners** — opt-in Codex and Claude scanner registrations with prompt packs for security, architecture, language, and quality reviews\n- **Pre-computed context** — `context.md` regenerated on every mutation for instant agent orientation\n- **Web dashboard** — real-time project overview with Kanban drag-and-drop, Graph v2 dependency exploration, Files/Health views, and optional multi-project server mode\n- **Minimal dependencies** — just Python + SQLite + click (no framework overhead)\n- **Session resumption** — `get_changes --since \u003ctimestamp\u003e` to catch up after downtime\n\n## How It Works\n\nFiligree gives one project three ways into a single SQLite database — agents\nthrough MCP tools, you through the CLI, and a browser through the dashboard.\nEvery mutation regenerates `context.md`, which the session hook injects back\ninto the agent at startup.\n\n```mermaid\nflowchart TD\n    Agent[\"AI coding agent\u003cbr/\u003e(Claude Code, Codex)\"]\n    Human[\"You + scripts\"]\n    Browser[\"Browser\"]\n\n    MCP[\"MCP server\u003cbr/\u003e(118 namespaced tools, stdio)\"]\n    CLI[\"filigree CLI\u003cbr/\u003e(--json, --actor)\"]\n    Dash[\"Web dashboard\u003cbr/\u003e(localhost:8377)\"]\n\n    DB[(\"SQLite database\u003cbr/\u003e.weft/filigree/filigree.db\")]\n    Ctx[\"context.md\u003cbr/\u003e(pre-computed orientation)\"]\n    Weft[\"Weft HTTP /api/weft/*\u003cbr/\u003e(optional federation)\"]\n\n    Agent --\u003e|\"calls tools over stdio\"| MCP\n    Human --\u003e|\"runs commands\"| CLI\n    Browser --\u003e|\"views, drags Kanban\"| Dash\n\n    MCP --\u003e|\"reads \u0026 writes issues\"| DB\n    CLI --\u003e|\"reads \u0026 writes issues\"| DB\n    Dash --\u003e|\"reads \u0026 writes issues\"| DB\n\n    DB --\u003e|\"regenerates on every mutation\"| Ctx\n    Ctx --\u003e|\"injected at session start\"| Agent\n\n    DB -.-\u003e|\"serves federation peers\"| Weft\n```\n\n**The work loop** is the same whether you drive it from the CLI or an agent\ndrives it through MCP tools: orient at session start, claim an issue atomically,\ndo the work, close it — and the next orientation is already regenerated.\n\n```mermaid\nsequenceDiagram\n    participant Dev as You / AI agent\n    participant Fg as Filigree\n    participant DB as .weft/filigree/ (SQLite)\n\n    Note over Dev,Fg: Session start\n    Dev-\u003e\u003eFg: filigree session-context\n    Fg-\u003e\u003eDB: read ready / in-progress / critical path\n    DB--\u003e\u003eDev: project snapshot\n\n    Dev-\u003e\u003eFg: filigree start-next-work --assignee me\n    Fg-\u003e\u003eDB: atomic claim + transition to working status\n    DB--\u003e\u003eDev: claimed issue (optimistic lock prevents double-work)\n\n    Note over Dev: do the work, commit\n\n    Dev-\u003e\u003eFg: filigree close \u003cid\u003e\n    Fg-\u003e\u003eDB: transition to terminal status\n    DB-\u003e\u003eDB: regenerate context.md\n    DB--\u003e\u003eDev: next ready work\n```\n\n**Each issue type enforces its own state machine.** Tasks are simple\n(`open → in_progress → closed`); features add review\n(`proposed → approved → building → reviewing → done`); bugs add a triage front\nand a *hard* verification gate, so a fix cannot close without a recorded\n`fix_verification`. The bug lifecycle below shows why \"ready\" is not the same as\n\"startable\" — a bug enters at `triage`, which has no single hop into work.\n\n```mermaid\nstateDiagram-v2\n    [*] --\u003e triage\n    triage --\u003e confirmed\n    triage --\u003e wont_fix\n    triage --\u003e not_a_bug\n    confirmed --\u003e fixing\n    fixing --\u003e verifying : requires fix_verification\n    verifying --\u003e closed : hard gate (fix_verification required)\n    verifying --\u003e fixing : kicked back\n    confirmed --\u003e wont_fix\n    wont_fix --\u003e [*]\n    not_a_bug --\u003e [*]\n    closed --\u003e [*]\n```\n\n## Quick Start\n\n```bash\npip install filigree        # or: uv add filigree\ncd my-project\nfiligree init               # Create the .weft/filigree/ store\nfiligree install             # Set up MCP, hooks, skills, CLAUDE.md, .gitignore\nfiligree create \"Set up CI pipeline\" --type=task --priority=1\nfiligree ready               # See ready work, including startability hints\nfiligree start-next-work --assignee \"$USER\" --advance\n# ...do the work and commit...\nfiligree close \u003cid\u003e\n```\n\nUse `start-next-work` or `start-work` to claim and transition work in one\natomic step. The older pattern of claiming and then manually updating status can\nrace another agent. Pass `--advance` when you want Filigree to walk safe\npre-workflow transitions first, such as moving a bug from `triage` through\n`confirmed` into its working state.\n\n## 3.0 Migration Snapshot\n\nFiligree 3.0 is a hard-break release for existing federation consumers and older\nlocal stores. New projects start directly in the current layout. Existing\nprojects should follow this operator checklist before resuming agent work:\n\n1. Stop all writers for the project: dashboard daemons, stdio MCP sessions, and\n   any scripts holding the legacy database open.\n2. Run `filigree init` from the project root. It migrates `.filigree/` into\n   `.weft/filigree/`, imports `.filigree.conf` into\n   `.weft/filigree/config.json`, and leaves an imported-conf breadcrumb.\n3. Update MCP consumers to namespaced tool names such as `issue_get`,\n   `finding_list`, and `work_start`. CLI verbs such as `start-next-work` and\n   `close` are unchanged.\n4. Repoint federation HTTP clients from `/api/loom/*` to `/api/weft/*`. Use\n   `WEFT_TOKEN` for the outbound registry token and `WEFT_FEDERATION_TOKEN` for\n   Filigree's inbound `/api/weft/*` and `/mcp` bearer token.\n5. Expect finding work views to default to active findings only. Pass\n   `--suppression all` on the CLI or `suppression=\"all\"` through MCP when you\n   need baselined, waived, or judged findings too.\n\nFull migration details live in [UPGRADING.md](docs/UPGRADING.md) and\n[MIGRATION-3.0.md](docs/MIGRATION-3.0.md).\n\n## Installation\n\n```bash\npip install filigree                     # CLI + MCP server + Web dashboard\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/foundryside-dev/filigree.git\ncd filigree \u0026\u0026 uv sync\n```\n\n### Entry Points\n\n| Command | Purpose |\n|---------|---------|\n| `filigree` | CLI interface |\n| `filigree-mcp` | MCP server (stdio transport) |\n| `filigree-dashboard` | Web UI (port 8377) |\n\n### Claude Code Setup\n\n`filigree install` configures everything in one step. To install individual components:\n\n```bash\nfiligree install --claude-code   # MCP server + CLAUDE.md instructions\nfiligree install --codex         # Codex MCP config via runtime autodiscovery\nfiligree install --hooks         # SessionStart hooks (project snapshot + dashboard auto-start)\nfiligree install --skills        # Workflow skill pack for agents\nfiligree doctor                  # Verify installation health\n```\n\nThe session hook runs `filigree session-context` at startup, giving the agent a snapshot of in-progress work, ready tasks, and the critical path. The skill pack (`filigree-workflow`) teaches agents triage patterns, team coordination, and sprint planning step by step.\n\n### Dashboard Authentication Scope\n\nThe dashboard is local-first and assumes loopback/local filesystem trust by default. The federation and MCP-over-HTTP surfaces are bearer-token gated **by default**: the daemon auto-mints a per-machine token at `\u003cstore_dir\u003e/federation_token` (mode 0600, gitignored) on first serve, and `filigree install` / `doctor --fix` pre-seed it. The token resolves in three tiers — the `WEFT_FEDERATION_TOKEN` environment variable (operator override, the only tier that works across hosts), then the store-dir token file, then absent (auth off). The older `FILIGREE_FEDERATION_API_TOKEN` and `FILIGREE_API_TOKEN` names are still accepted as deprecated fallbacks and log a migration warning. This token is federation/deconfliction plumbing, not a security secret. The token value is never reported by `/api/health`, but the health payload does report which auth scope is enabled. Rotate with `filigree rotate-federation-token` (effective at the next daemon restart).\n\n| Route class | Authentication |\n|-------------|----------------|\n| Dashboard UI (`/`) | Open under the local loopback trust boundary |\n| Classic dashboard API (`/api/issues`, `/api/issue/{id}`, `/api/health`) | Open under the local loopback trust boundary |\n| Federation and scanner ingest (`/api/weft/*`, `/api/scan-results`, `/api/observations`, `/api/v1/scan-results`, `/api/v1/observations`) | Bearer token when one resolves (auto-minted by default; `WEFT_FEDERATION_TOKEN` overrides) |\n| MCP HTTP endpoint (`/mcp`, `/mcp/*`) | Bearer token when one resolves (auto-minted by default; `WEFT_FEDERATION_TOKEN` overrides) |\n\n## Why Filigree?\n\nFiligree is designed for a specific niche: local-first, agent-driven development. It is not a replacement for GitHub Issues or Jira.\n\n**Is Filigree suitable for my project?**\nUse Filigree when your priority is plug-and-play agent coordination: install it, run `filigree init` and `filigree install`, open your agent, and immediately get project context, tickets, scanner findings, and local workflow tools. Do not use Filigree when the issue database, comments, scans, or integrations would contain secrets, regulated data, customer data, confidential business information, or anything that must be encrypted or access-controlled beyond normal local filesystem protections and HTTPS transport you provide yourself.\n\n| Feature | Filigree | GitHub Issues | Jira |\n|---------|----------|---------------|------|\n| Agent-native MCP tools | Yes | No | No |\n| Works offline, no account needed | Yes | No | No |\n| Enforced workflow state machines | Yes | Limited | Yes |\n| Dependency graph + critical path | Yes | Limited | Yes |\n| Structured queries and filtering | Yes | Yes | Yes |\n| Multi-user cloud collaboration | No | Yes | Yes |\n| Integration ecosystem (CI, Slack) | No | Yes | Yes |\n\n## When NOT to Use Filigree\n\nFiligree is designed for one niche well. It is the wrong tool if you need:\n\n**Team collaboration across machines.**\nFiligree has no cloud sync, no accounts, and no network-accessible API beyond localhost. If your team of humans needs to file bugs, assign tickets, and comment across different machines, use GitHub Issues, Linear, or Jira.\n\n**Integration with your existing toolchain.**\nFiligree does not connect to CI pipelines, Slack, PagerDuty, or third-party services. If your workflow requires automated ticket creation from alerts or Slack-based triage, Filigree will not fit without custom scripting.\n\n**A persistent project record outlasting the repository.**\nYour `.weft/filigree/` directory lives with your project. If you need an audit trail that survives repository deletion or is accessible after the project ends, use a hosted service.\n\n**Multi-project portfolio management.**\nThe web dashboard supports switching between local projects, but Filigree has no cross-project reporting, resource allocation, or roadmap views. It tracks tasks, not portfolios.\n\n**Mobile or browser-based access.**\nThe dashboard runs on localhost. If stakeholders need to read or file issues from their phone or a machine where the project is not checked out, Filigree is not the right choice.\n\n**Secure or sensitive data.**\nNothing in Filigree is encrypted or secured beyond ordinary local filesystem protections and standard HTTPS if you provide it. Do not use this system for secure or sensitive data.\n\n**The sweet spot**: one developer or agent team, one project, offline or airgapped, where you want structured workflow enforcement and agent-native tooling without standing up external infrastructure.\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Getting Started](docs/getting-started.md) | 5-minute tutorial: install, init, first issue |\n| [CLI Reference](docs/cli.md) | All CLI commands with full parameter docs |\n| [MCP Server Reference](docs/mcp.md) | 118 MCP tools for agent-native interaction |\n| [Federation Contracts](docs/federation/contracts.md) | Classic and Weft HTTP generation contracts |\n| [Workflow Templates](docs/workflows.md) | State machines, packs, field schemas, enforcement |\n| [Agent Integration](docs/agent-integration.md) | Multi-agent patterns, claiming, session resumption |\n| [Python API Reference](docs/api-reference.md) | FiligreeDB, Issue, TemplateRegistry for programmatic use |\n| [Architecture](docs/architecture.md) | Source layout, DB schema, design decisions |\n| [Examples](docs/examples/) | Runnable scripts: multi-agent, workflows, CLI scripting, planning |\n\n## Priority Scale\n\n| Priority | Label | Meaning |\n|----------|-------|---------|\n| P0 | Critical | Drop everything |\n| P1 | High | Do next |\n| P2 | Medium | Default |\n| P3 | Low | When possible |\n| P4 | Backlog | Future consideration |\n\nFull definitions: [Workflow Templates — Priority Scale](docs/workflows.md#priority-scale)\n\n## Development\n\nRequires Python 3.11+. Developed on 3.13. Node.js 24 is also required for the\nNode-backed static dashboard pytest tests and dashboard JavaScript quality\ngates.\n\n```bash\ngit clone https://github.com/foundryside-dev/filigree.git\ncd filigree\nuv sync --group dev\n\nmake ci              # ruff check + mypy strict + pytest with 85% coverage gate\nmake lint            # Ruff check + format check\nmake format          # Auto-format with ruff\nmake typecheck       # Mypy strict mode\nmake test            # Pytest\nmake test-cov        # Pytest with coverage (fail-under=85%)\n```\n\n### Key Conventions\n\n- **Ruff** for linting and formatting (line-length=140)\n- **Mypy** in strict mode\n- **Pytest** with pytest-asyncio for MCP server tests\n- **Coverage** threshold at 85%\n- Tests in `tests/`, source in `src/filigree/`\n\n## Acknowledgements\n\nFiligree was inspired by Steve Yegge's [beads](https://github.com/steveyegge/beads) project. Filigree builds on the core idea of git-friendly issue tracking, focusing on MCP-native workflows and local-first operation.\n\n## License\n\n[MIT](LICENSE) — Copyright (c) 2026 John Morrissey\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoundryside-dev%2Ffiligree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoundryside-dev%2Ffiligree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoundryside-dev%2Ffiligree/lists"}