Tramuri

English · Português (Brasil)

From intent to verified outcomes.

Tramuri is open-source, local-first infrastructure for turning product and business objectives into coordinated work and verifiable outcomes. It helps people, agents, and tools carry context between sessions and distinguish completed work from results that have actually been reviewed.

Tramuri is designed for Product Engineers, Forward Deployed Engineers (FDEs), and product teams. It works without requiring a source-code repository, an LLM, or a particular agent framework.

What Tramuri provides

• Missions and Success Contracts to describe an objective and its acceptance criteria.
• Persistent knowledge with source references and history.
• Execution and evidence records that keep work, supporting references, and assessment distinct.
• Verified outcomes based on explicit criterion reviews; a completed execution alone does not mark a Mission as achieved.
• Project Discovery as an optional way to inventory a code project. Scanning does not execute repository files and excludes sensitive paths by default.
• Capability Discovery to catalog supported project-local skills, instructions, agents, hooks, and MCP declarations without executing or connecting to them.
• A native Rust CLI and a Python SDK backed by the same Rust core.

The published Python SDK includes a prebuilt Rust extension on supported platforms; users do not need a Rust toolchain.

Tramuri stores its local project state under .tramuri/, with SQLite at .tramuri/database/tramuri.sqlite3 and the latest scan report under .tramuri/discovery/. Evidence is recorded as references; Tramuri does not fetch external resources or store scanned file contents as evidence. The capability catalog is a derived snapshot; declared MCP servers and hooks are not considered operationally verified.

Prerequisites

PyPI installations use prebuilt wheels on supported platforms. You do not need Rust installed.

Install

Python SDK

Install Tramuri into an existing Python project:

uv add tramuri

Or use pip:

python -m pip install tramuri

CLI and assistant integrations

The Tramuri package includes the CLI distribution and project integration installer. Install the CLI in an isolated tool environment:

uv tool install tramuri
tramuri --version

pipx install tramuri is also available as an isolated-install alternative. If the tramuri command is not found after installation, run uv tool update-shell and reopen your terminal.

After a new Tramuri release is published, update it with the package manager used to install it:

uv tool upgrade tramuri
# If installed with pipx instead:
pipx upgrade tramuri
tramuri --version

Install Tramuri into the project for the assistant you use, preserving existing instructions and hooks:

tramuri install --platform codex --project
tramuri init .

Then describe the outcome in the assistant chat, for example: “I want to work as a Product Engineer on improving customer onboarding” or “I am taking over this integration as an FDE.” The installed Tramuri skills guide Mission and Success Contract setup, record the selected work perspective, and continue with the task; a project scan is optional. After a coherent work session changes Mission records, the assistant refreshes and opens the local report once. You can also ask “open the Tramuri report” or run tramuri status --open yourself.

The local report opens in English or Brazilian Portuguese and shows work perspective (Product Engineer/FDE) separately from the recorded actor. Actor labels are provided by the caller and are not authenticated; Tramuri does not infer a current Mission owner.

tramuri capabilities --type skill --json filters the latest declarative catalog. Scanning honors project ignore rules and sensitive-path exclusions; it does not read global agent settings, execute hooks, start MCP servers, or make network connections.

Codex, Claude Code, Cursor, and Gemini CLI receive native project instructions, a Tramuri overview skill plus focused setup, discovery, Mission, and integrity skills, and a project-local session-start hook. Hooks emit only a static reminder; they do not read the database or attach Mission data. The assistant must explicitly run Tramuri commands when it needs workspace context. Hooks follow each host's project trust settings, and installation preserves unrelated instructions and hook entries. Cursor uses .cursor/rules/tramuri.mdc, .cursor/skills/tramuri/, and .cursor/hooks.json; the other hosts use their native instruction, skill, and hook locations.

Copilot project instructions and skills remain supported; Copilot hooks are not installed by Tramuri.

tramuri install --project --platform copilot
tramuri install --project --platform claude
tramuri install --project --platform cursor
tramuri install --project --platform gemini

tramuri status summarizes the workspace, tramuri status --open generates and opens the local report, and tramuri resume --mission <id> reconstructs recorded work and readiness for the selected next activity. A Mission can start without criteria; its Outcome stays pending until required criteria are added and reviewed. Readiness is advisory and never blocks execution:

tramuri mission create --objective "Investigate onboarding drop-off"
tramuri readiness assess --mission <id> --activity discover --state needs_review \
  --gap "Interview data is not available yet"
tramuri status --open

Use tramuri readiness show --mission <id> to review the current assessment and its history. Changing the objective, Success Contract, or explicitly linked Knowledge/Capabilities marks the latest readiness as stale while retaining the original assessment. tramuri mission list discovers Missions. The report files are .tramuri/reports/tramauri.html, tramauri.md, and tramauri.json. Opening an older supported database can apply its existing schema migrations; status reads do not change Mission, execution, evidence, or outcome records. These commands work without an assistant; integrations are optional.

Knowledge and discovered Capabilities can be explicitly associated with a Mission using tramuri mission link-knowledge and tramuri mission link-capability. tramuri resume --mission <id> includes only those recorded associations. Tramuri does not infer Mission relevance; capability links retain the observed source hash and become changed, missing, or unverified after later scans. Actor attribution is caller supplied and is not authenticated.

Follow complete synthetic projects from setup to handoff in the Product Engineer and FDE examples.

How an assistant can use Tramuri

The project installer is intended to give a supported assistant persistent, platform-native guidance for when Tramuri is useful. The skill explains the workflow; the CLI performs Tramuri operations against local project state. Both are optional, and the assistant remains free to use other tools.

Mission creation does not require a Git repository or project scan. See the product vision for Tramuri's scope and principles, and the changelog for release history.

Project status

Tramuri is in active early development. Project and Capability Discovery, persistent knowledge, Missions, explicit Knowledge/Capability links, manual Execution and Evidence records, and criterion assessments are part of the current product. Capability formats are platform-specific; only documented project paths are recognized. Versioned Context Pack and Evidence Pack export is planned; it will use explicit selection and authorization and will be safe by default.

Community

• Contributing
• Code of Conduct
• Security policy
• Support
• License (Apache-2.0)