Totem

Totem is a lightweight, flat-file issue tracker built for AI-agent workflows.

Each issue is a markdown file — a totem — checked into the repo alongside the code it describes. Agents create and update totems at the speed of code edits, without the overhead of a heavyweight tracker. When you need portfolio-level visibility, many totems roll up to Jira for project, portfolio, and initiative tracking.

Use it through:

• totem — CLI for create, list, update, show, query
• totem-tui — interactive terminal UI
• totem-serve — local web UI with GraphQL API, real-time updates, and worktree management

Why Totem

• Agent-native. Coding agents read, create, and update totems from CLI or GraphQL at edit speed. No web forms, no SaaS round-trips, no JQL.
• Lightweight. No database, no SaaS account. A .totem/ directory and you're done.
• Git-native. Markdown in git means every change is attributed, diffable, and version-controlled alongside the code it describes.
• Rolls up to your PM stack. Tag totems with external IDs (Jira, Linear, GitHub Issues). Companion tools like PASIV push completions to your tracker for project, portfolio, and initiative visibility — Totem itself stays stack-agnostic.

Status

Totem is early-stage. Schema and APIs may change as we iterate.

Installation

Once releases are published to the Inceptyon Labs Homebrew tap:

brew tap inceptyon-labs/tap
brew install totem

Or build from source:

git clone https://github.com/inceptyon-labs/totem.git
cd totem
mise trust && mise setup
mise build
mise install   # copies binaries to ~/.local/bin

Quick Start

cd your-project
totem init                          # creates .totem/ and .totem.yml
totem create "Fix login bug" -t bug
totem list
totem-tui                           # interactive browser
totem-serve                         # web UI at http://localhost:8080

Configuration

totem init creates a .totem.yml at the project root. See the file for inline comments on each setting.

Contributing

See CONTRIBUTING.md. Please review our Code of Conduct and Security Policy before opening issues or PRs.

License

Apache-2.0. See LICENSE and NOTICE for attribution.