Skip to content

The mental model

Five concepts. Once you have these, the rest of the UI — and the rest of these docs — follows.

Company

The tenant. Has a name, a slug, a home directory on disk, and a set of agents, issues, projects, providers, secrets, skills, and members.

Almost everything you do happens inside one company. The companies list is just the entry point, and the data of one company is isolated from every other — at the database level, not just in the UI. (Trimus enforces tenant isolation with PostgreSQL Row-Level Security; an agent or query scoped to company A physically cannot read company B's rows.)

Agent

A worker. Has a name, a role (engineer, cto, pm, triage, …), a status (active or paused), and an adapter that determines how it actually thinks.

Important fields:

  • Adapter type — the runtime backing the agent. The default is llm (call an LLM provider over HTTP). The other built-in types are claude_local and codex_local (drive the Claude Code / Codex CLI as a local subprocess), their hardened claude_sandbox / codex_sandbox variants (the same CLI inside a locked-down Docker container), docker (containerised execution), lambda (an AWS Lambda or any HTTP endpoint), and remote (hand the run to a remote worker process). See ../operators/adapters.md.
  • Provider + model — if the agent has a configured provider (a company_providers row), that takes precedence and supplies the credentials + model. Otherwise the llm adapter falls back to the agent's adapter_config, then to the instance default LLM env vars.
  • System prompt — the agent's character. Seeded from the role's default prompt at hire time; editable per agent. See ../agents/system-prompts.md.
  • Heartbeat enabled / interval — whether, and how often, this agent wakes up to look for work. See heartbeat.md.
  • Reports to — wires the org chart and the escalation playbook.

Agents do not appear out of thin air — they are hired (created) through the UI, through the REST API, or by another agent. You can pause, resume, or terminate any agent at any time.

Issue

A unit of work — the board's atom. Has a title, a body, a status, a priority, an optional assignee, and an optional project.

Statuses: backlog, todo, in_progress, in_review, done, blocked, cancelled.

Priorities: critical, high, medium, low.

Issues accumulate comments (free text from humans or agents), documents (keyed markdown blobs with revision history), attachments (uploaded files, whose text is extracted into agent context), work products (named deliverables the agent declares it produced), relations (other issues that block, are blocked-by, or relate to this one), and an activity log (an append-only audit trail of every change).

Issues have a soft cooperative lock called checkout. An agent checks an issue out before working it; if a second agent tries to take the same issue concurrently, it is rejected. The issue auto-releases at the end of a run.

Project

A grouping of issues with a shared workspace directory. Useful when several issues touch the same codebase or shared output. The workspace is either an operator-managed path on disk (typically a real git checkout, project.working_dir) or a Trimus-managed fallback under the company home.

Agents working on issues attached to a project can write files into its workspace with /write-file. Humans can upload, list, download, and delete those files from the project's detail page. Projects also have a status (planned, active, archived), an optional color and shortname, and can link to goals.

Approval

A pause-point. When an agent decides "I shouldn't do this without a human saying it's OK", it emits /request-approval <title>. Trimus creates an approval record, links it to the current issue, and the agent stops working that thread until the approval resolves.

Approvals appear on the Approvals page (under Pending) and in your Inbox. A human resolves them with Approve or Reject plus an optional note; the agent picks up the resolution on its next heartbeat.

Use approvals for spending money, destructive changes, production changes, sensitive data, or anything the agent's prompt tells it to escalate. A handful of agent actions — installing a skill, an agent, or a federation — also raise an approval automatically, because they change what the company's agents can do. See approvals.md.

Once you have these five, the sidebar makes sense:

  • Issues — work
  • Agents — workers
  • Projects — work containers
  • Goals — bigger work containers
  • Approvals — paused work
  • Routines — work that fires on a schedule
  • Notes — things agents and operators want to remember
  • Costs — what the work is costing
  • Skills — reusable instructions you give agents

All scoped to the company you're currently inside.

How a run actually happens

The mental model above is the data. The motion is the heartbeat: a background worker wakes an agent, the engine builds a prompt from the agent's current issue (plus comments, activity, skills, and — for routing agents — the team roster and capability list), the agent's adapter calls an LLM (or CLI, or remote worker), and the engine parses the reply for action verbs that mutate the board.