Open-source tool that helps you write better docs with AI — and keep them structured and connected.
Syntagraphia combines the Greek words σύνταξη (syntax, structure, arrangement) and γραφή (writing, description, representation), reflecting the project’s goal of turning information into a well-structured knowledge graph.
As vibe-coded projects grow, it's easy to lose context of what was built and why. Syntagraphia keeps your features, tech specs, tasks, and verifications in a single local SQLite database by default, or a provisioned PostgreSQL database, linked by explicit relations — so you (and your AI agents) always stay on the same page.
Syntagraphia is a CLI (with an optional web UI). Document content lives entirely in the DB; there
are no .md files or features//tasks/ directories to manage on disk.
For the complete install, clean reinstall, and first-project walkthrough, see INSTALLATION.md.
# Install once; humans and AI agents use the same command:
npm install --global syntagraphia
syntagraphia --versionRequires Node ≥ 22 (uses the built-in node:sqlite; PostgreSQL uses the pure-JavaScript pg client).
Syntagraphia keeps every project on your machine in a single global DB at
~/.syntagraphia/project-tracker.db. Create a project, then scope doc commands to it with
--project <id|slug>:
# 1. Create a project and capture its constitution
syntagraphia project create "My App"
# → prints slug/id, e.g. my-app (id 1)
# 2. Add and customize the agent instructions for this project
cp "$(npm root --global)/syntagraphia/AGENTS_template.md" AGENTS.md
# 3. Create connected docs for a feature (all --project <slug>)
syntagraphia doc create feature user-auth --project my-app
syntagraphia doc create tech_spec user-auth --project my-app
syntagraphia doc create task user-auth --suffix backend --project my-app
syntagraphia doc create verification user-auth --project my-app
syntagraphia relate 1 2 has_spec --project my-app # feature → spec
syntagraphia relate 1 3 has_task --project my-app # feature → task
syntagraphia relate 1 4 verifies --project my-app # feature → verification
# 4. View / edit
syntagraphia doc list --project my-app
syntagraphia search "authentication" --project my-app --status IN_PROGRESS
syntagraphia doc show user-auth --project my-app
syntagraphia doc update user-auth ./notes.md --project my-app
syntagraphia doc checklist add user-auth "Login flow is documented" --project my-app
syntagraphia doc checklist update 1 --status DONE --commit https://github.com/org/repo/commit/abc123 --project my-app
syntagraphia status --project my-app
# 5. Web UI (bundled SPA + API, one process/port — serves ALL projects)
syntagraphia ui
# Optional: switch the machine-wide backend (no data migration)
syntagraphia db status
syntagraphia db use postgres --url postgres://user:password@host:5432/syntagraphia
syntagraphia db use sqliteSwitch repos? Just project create another one and pick it from the UI dropdown. The same install
tracks all of them.
Copy the packaged AGENTS_template.md to your project's AGENTS.md or CLAUDE.md, then customize
it for the project's conventions and workflow. The template is included in the npm package and is
also available at the repository root.
All one-shot commands support --json (machine-readable). Doc-level commands require
--project <id|slug> to scope which project they touch.
| Command | Description |
|---|---|
project create <name> [--constitution-file <path>] [--force] |
Create a project and capture its constitution; --force re-captures an existing same-named project's constitution |
project list |
List all projects on this machine |
db status |
Show the active SQLite/Postgres backend |
db use sqlite |
Switch to the local SQLite backend |
db use postgres --url <connection-string> |
Validate and switch to PostgreSQL |
template list |
List document templates and whether each uses the packaged default or a custom override |
template show <type> |
Show a document template's Markdown content |
template set <type> <file.md> |
Set the template used for new documents of a type |
template reset <type> |
Restore the packaged default template for a type |
doc list --project <p> [--type] [--status] |
List documents in a project |
search [<term>] --project <p> [--type] [--status] |
Search document slugs, suffixes, and content |
doc show <id|slug> --project <p> |
Show a document (content + relations) |
doc create <type> <slug> --project <p> [--suffix] [--status] |
Create a document from a template |
doc set-status <id> <STATUS> --project <p> |
Change status (DRAFT|IN_PROGRESS|REVIEW|DONE) |
doc checklist list <id|slug> --project <p> |
List a document's structured checklist |
doc checklist add <id|slug> <text> --project <p> [--status] [--commit] |
Add a checklist item |
doc checklist update <item-id> --project <p> [--text] [--status] [--commit|--no-commit] |
Update a checklist item |
doc checklist remove <item-id> --project <p> |
Remove a checklist item |
doc update <id|slug> <file.md> --project <p> |
Overwrite content from a Markdown file |
doc write <id|slug> --project <p> --file <path>|--stdin |
Legacy content overwrite command |
doc edit <id|slug> --project <p> |
Deprecated; use the UI or doc update |
relate <src> <tgt> <type> --project <p> |
Link documents (has_spec|has_task|verifies|implements); same project only |
constitution show --project <p> |
Show the project's constitution |
status --project <p> |
Dashboard summary + orphan check |
ui [--port 3001] [--no-open] |
Start the web UI (long-running, serves all projects) |
Run syntagraphia --help for the full synopsis.
doc create uses the packaged templates in templates/doc-content by default. To customize the
template for new documents of a type, provide a Markdown file:
syntagraphia template set feature ./feature-template.md
syntagraphia template list
syntagraphia template show featureOverrides are stored machine-wide in ~/.syntagraphia/templates/ and apply only to documents
created after the override is set. Existing document content is not changed. Use
syntagraphia template reset <type> to return to the packaged default.
Templates support {{slug}} for the document slug, {{suffix}} for an optional task/spec suffix,
and {{suffix_label}} for the suffix including its surrounding parentheses.
All documents for a topic share a slug (e.g. user-auth). Relations tie them together:
has_spec— feature → tech_spechas_task— feature → taskverifies— feature → verificationimplements— task → tech_spec (optional)
Features, tasks, tech specs, and verifications have a structured checklist separate from their Markdown content:
- features use Acceptance Criteria;
- tasks use Subtasks;
- tech specs use Technical Checklist;
- verifications use Validation Checklist.
Every item has its own status (DRAFT, IN_PROGRESS, REVIEW, or DONE) and may include an
optional HTTP(S) link to the Git commit that completed it. Checklist items are project-scoped and
keep their own order. Existing Markdown checkbox lists are not imported automatically.
syntagraphia status reports orphan tasks/verifications (those with no parent), enforcing the rule
that work should always trace back to a feature or spec.
syntagraphia search performs a case-insensitive search within the selected project's document
slugs, optional task/spec suffixes, and Markdown content. The term and type/status filters are
optional, so it can also list documents matching a type or status.
- CLI / storage — Node ≥ 22 + built-in
node:sqliteor the pure-JavaScriptpgclient. - Web UI — React + Vite, built and bundled into the package; served by the same Express process as the API.
- Distribution — npm. Install once globally with
npm install --global syntagraphia; the same command works across all repos for both humans and AI agents.
git clone https://github.com/festoinc/Syntagraphia.git
cd Syntagraphia
npm install
npm run dev # API server (:3001, DB-backed) + Vite UI (:5173, proxies /api → :3001)The dev script runs the new DB-backed server (syntagraphia ui --no-open) plus Vite's dev server
with HMR. Build the bundled SPA with npm run build:ui (also runs on prepack/prepublishOnly).
MIT © Anatolii Fesiuk