Getting Started

From zero to a running Trurlic with a recorded architectural decision and a connected AI coding agent.

Prerequisites

• Linux, macOS, or Windows. Trurlic is a single static binary — no runtime dependencies.
• curl (or wget) for the installer.
• An LLM API key only if using trurlic design (Socratic conversations). The MCP server, CLI, and map are fully offline.

1. Install

curl -fsSL https://raw.githubusercontent.com/trurlic-labs/trurlic/main/install.sh | bash

Or with Rust:

cargo install trurlic                     # requires Rust 1.88+

Pre-built binaries for Linux, macOS, and Windows are on the Releases page.

2. Initialize

cd your-project
trurlic init

This creates a .trurlic/ directory in your project root and adds .trurlic/.state/ to your .gitignore (session data is local, not versioned).

The .trurlic/ directory is meant to be committed to git — it is your architecture’s source of truth.

3. Define a component

trurlic add component auth -d "Authentication and token management"
trurlic add component database -d "Persistence layer"
trurlic add connection auth database

Components are the building blocks of your architecture graph. Connections represent data or control flow between them.

4. Record a decision

trurlic decide auth \
  --choice "JWT with DPoP binding" \
  --reason "Stateless, no session store needed" \
  --alternative "Session cookies — rejected: requires server-side state"

The decision is now a TOML file in .trurlic/decisions/ and indexed in graph.toml.

5. Start the MCP server

trurlic serve

The MCP server starts on stdio transport — ready for any MCP-compatible coding agent. Leave it running and connect an agent (see MCP Server for setup).

What just happened

You defined an architecture and made it queryable:

1. trurlic init created the .trurlic/ directory with project.toml, a graph.toml edge index, and a .state/ directory for sessions.
2. trurlic add component wrote TOML node files to .trurlic/components/.
3. trurlic add connection recorded a directional edge in the graph index.
4. trurlic decide wrote a decision to .trurlic/decisions/ with full metadata — choice, reason, alternatives, timestamp, attribution — and rebuilt the graph index atomically.
5. trurlic serve started an MCP server that exposes twelve tools for querying and mutating the graph.

Every write validated the full graph before touching disk. If any step had produced an invalid state — a dangling edge, a cycle, a schema violation — it would have been refused with a clear error.

Next: connect your IDE

The fastest way to connect an IDE agent is trurlic install:

trurlic install --ide cursor         # Cursor
trurlic install --ide claude-code    # Claude Code
trurlic install --ide windsurf       # Windsurf

See CLI Reference — trurlic install for all supported targets, or the Integrations section for IDE-specific guides.

Next: design conversations

Quick decisions are useful for straightforward choices, but most architectural decisions benefit from structured thinking. trurlic design runs a Socratic conversation — the AI asks probing questions, you think through tradeoffs, and decisions are recorded as you go:

export ANTHROPIC_API_KEY="sk-ant-..."
trurlic design auth

See Design Conversations for the full walkthrough.

Next: bootstrap from existing code

For existing codebases, trurlic bootstrap lets an AI coding agent read your source code and populate the decision graph autonomously:

trurlic bootstrap
trurlic serve
# In your coding agent: advance(component="project", task_type="bootstrap")

See Bootstrap for details.

Next steps

• MCP Server — connect your IDE agent to the decision graph
• Design Conversations — Socratic design flow
• Bootstrap — extract architecture from existing code
• Interactive Map — visualize the graph in the browser
• Core Concepts — understand the decision graph, advance loop, and context briefs
• CLI Reference — complete command-line reference