Skip to main content

Agenturm — Know what your agents are doing. Local observability for coding agents.

Inspect the evidence behind your agents’ work.
Attribute each run, examine what supports “done,” and retain the context for review.

Explore the workflow →  ·  Documentation  ·  What’s new in 0.2.4

CI PyPI version Local by default MIT license

What it adds to an engineer's workflow

With concurrent agents, the expensive question becomes which run produced this result, and what supports it? A completion message does not tell you whether the selected worker ran the check, whether an edit followed it, or whether you are looking at a different execution's evidence.

Agenturm reads supported local agent records and configured OpenTelemetry signals into SQLite. Its practical value is in three jobs: attribute concurrent work, inspect recorded validation and its gaps, and carry evidence and engineering decisions across sessions. Exact identities keep workers separate; Review distinguishes agent claims from recorded results; saved tasks retain a brief, rationale and linked runs. It does not independently attest command execution or establish the current worktree's correctness.

When you need to… Agenturm gives you…
Decide which terminal to return to Working sessions, explicit waits, an attention inbox, and reported completions awaiting review
Understand a team of agents Expandable parent/worker trees when the runtime records exact delegation; each worker has its own inspector
Catch up without rereading a transcript A human-readable task, recorded progress, and Overview / Prompts / Details
Assess an agent’s “done” Recorded checks, errors, later edits, and coverage limits in Review
Investigate a broken tool call Captured MCP arguments, responses, duration, and a linked trace when available
Continue the task in another session A saved brief, versioned decisions, linked runs, workspace capture, and a handoff you review before sharing

Reply to agents and approve their requests in their own terminals. Agenturm monitors their work; it does not launch or control them.

In 0.2.4: agenturm review exposes the same scoped evidence without opening the cockpit, as text, JSON or a frozen Markdown/HTML receipt. It shows a check followed by an edit as a reason to inspect and rerun affected checks, and discloses missing ownership or capture. Engineering contracts, a concrete example, and CLI usage · Standalone HTML.

See it in action

Agenturm 0.2.0 terminal showing distinct agent rows, delegated workers, recorded states, and the selected agent’s overview. Synthetic example records.

Try the interactive walkthrough on agenturm.dev →

Watch the 37-second terminal walkthrough · Animated preview · Written transcript

Follow a refresh-token fix: find a worker that needs input, read the requests, inspect a reported test result alongside a later edit, investigate a failed MCP call, and preview a handoff. The browser walkthrough is a simplified, interactive explanation. Screenshots are captured from the actual v0.2.0 terminal. All demo records are synthetic.

Get your first useful view

Requires Python 3.11+. Use uv or pip to install.

Keep your coding agents open. In another terminal, run:

uvx agenturm

Agenturm starts or attaches to its local receiver. Recent supported Codex, Claude Code, OpenCode, and Pi records are discovered locally; those agents do not need a restart. No Agenturm account, subscription, or provider API key is needed for local monitoring.

  1. In Agents, select a session with ↑ / ↓. Expand a recorded delegation with →.
  2. Press Enter to inspect. Use Overview to catch up, Prompts to read requests, and Details for source and usage information.
  3. Open Review for the selected session’s captured checks and edits. Press w for the attention inbox or b to save the task for later.

An empty screen means no supported recent records have been discovered yet. Run a supported agent and open collection diagnostics with d. Agenturm does not seed your workspace with example sessions. See discovery, custom paths, and troubleshooting.

For a persistent command:

uv tool install agenturm
agenturm

Or install with pip in your Python environment:

pip install agenturm
agenturm

To upgrade a pip installation, run pip install --upgrade agenturm.

To upgrade, run uv tool upgrade agenturm, then restart Agenturm and any separately running receiver. Other installation methods.

From activity to understanding

See the agent and its workers

Today puts active work and work needing review within reach; History keeps earlier sessions available. Search by task or project. Switch between the tree and flat list with f.

The roster uses In progress, Needs attention, and Ready for review, with precise status evidence in the inspector. Spaced task blocks and deeper tree guides keep workers readable.

Task labels stay anchored to the first substantive recorded request. Model changes, acknowledgements, and later steering stay in Prompts without renaming the task. The source line stays short; recent activity and status evidence live in the inspector. Task identity and capture limits.

A parent and its workers retain independent states. A completed parent can still have a working child; the branch summary makes that visible. Missing parent evidence stays explicit. Relationships use exact runtime identifiers, rather than guesses from similar tasks or nested spans. Hierarchy support and limits.

Read the request with its context

Overview collects the latest agent-reported update, recorded work, results, and delegated children. Prompts gives each request a readable place of its own, separates captured runtime scaffolding, and keeps the original text available. Details holds IDs, provenance, and reported usage.

In Prompts, ↑ / ↓ chooses a request; Enter / → moves into the reader and ← returns to the request list. [ / ] changes requests from the reader; z shows the original text. Reading positions survive section changes. Complete keyboard guide.

Review the evidence behind “done”

Ready for review means an agent reported completion. Open Review to inspect the captured checks, failures, edits, and coverage for that session. A passing command followed by a later edit is different from a check on the current files. Loaded evidence can be partial; the interface says so.

Marking a run reviewed records your acknowledgement. Agenturm does not execute a fresh test suite or certify the change. MCP and trace inspectors let you go deeper when the producer recorded the corresponding arguments, results, and execution links.

Keep the task across sessions

Press b to save a task. Write the intent, acceptance criteria, constraints, open questions, and next action. Record accepted or rejected approaches with their rationale. Link runs deliberately and capture workspace changes when you need a handoff.

Handoff previews the saved brief, decisions, linked evidence, and captured diff before you copy it or export Markdown + self-contained HTML. Paste it into the agent you choose. Saved tasks are local and remain editable while the receiver is offline.

The same workflow is available from the CLI:

# Creates a task and prints its ID. Use that ID in the commands below.
agenturm task create --title "Fix refresh token expiry" --workspace . \
  --notes "Keep the public API. Next: add an expiry regression." --snapshot

agenturm task brief TASK_ID --intent "Reject expired refresh tokens" \
  --next-action "Add the expiry regression, then rerun tests"
agenturm task decide TASK_ID --kind accepted --text "Keep the public API" \
  --rationale "Existing clients depend on it"
agenturm task handoff TASK_ID --output ./refresh-handoff.md

The export creates .md and .html files and refuses to overwrite existing destinations. Workspace capture reads Git changes; it does not run checks or attribute every edit to one agent. Saved tasks, decisions, and handoffs.

Connect the tools you already use

Source How it connects What to expect
Codex, Claude Code, OpenCode, Pi Automatic discovery of supported local records Recent sessions and recorded activity; available signals depend on runtime and record format
Pydantic AI, Google ADK, Gemini CLI, and other supported OTLP producers Configure OpenTelemetry export to the local receiver Emitted traces, logs, metrics, and correlation identifiers
Supported Python SDKs Explicit automatic-capture launcher or documented integration Captures supported SDK calls; existing processes may need a restart through the launcher
Your own Python or JavaScript agent Instrument with the clients or OTLP Only the evidence and identifiers your producer emits

Exact delegation is supported for documented Codex, Claude Code, and OpenCode shapes. Automatic Pi subagent linking is not independently verified. A nested telemetry span alone is not treated as an agent. See the integration guide, Python capture, JavaScript client, and receiver configuration.

Local storage, explicit sharing

The built-in receiver defaults to 127.0.0.1:14318. Local monitoring and recorded-progress summaries work without a cloud service. Telemetry now defaults to the private Agenturm state directory, with a local bearer token and 14-day retention for genuinely new managed stores. Existing explicit databases keep their retention policy. Saved tasks use a separate database, so telemetry retention does not delete your brief or decisions. Storage, authentication and migration.

Captured messages, commands, and tool results can contain project secrets. Credential redaction is best effort. --metadata-only omits native session content from future ingestion; it does not erase existing records. Saved workspace captures and handoffs need your own review before sharing. Capture and privacy boundaries.

Optional AI summaries send documented session evidence to your configured provider only when explicitly requested. AI summary setup and data.

The keys you’ll use every day

Key Action
1–7 Agents, Activity, MCP Calls, Traces, Host, Metrics, Findings
↑ / ↓, Enter Select and inspect
→ / ←, f Expand/collapse agents; switch tree/flat presentation
/, o Search; choose sort order
Ctrl+← / Ctrl+→, m Switch inspector sections
Tab / Shift+Tab Move between controls
w, b Attention inbox; saved tasks
t, x, c Linked trace; evidence export; copy details
Esc / Alt+← Return / navigate back
F1, ?, Ctrl+P Contextual help, help, command palette
q Quit

Choose Current (Alpine Ember), Bright, Dark, or Solarized through Ctrl+P → Theme. See the daily workflow guide for the full interface.

Status and contributing

Agenturm is open source under the MIT license. Version 0.2.4 includes the agent hierarchy, readable inspector, completion review, attention inbox, and saved-task continuity workflows. Signal coverage depends on the source. See the current quality report for measured performance, stability and remaining acceptance limits.

git clone https://github.com/abhishekash/agenturm.git
cd agenturm
uv sync
uv run agenturm
uv run python -m unittest discover -s tests -v

Contributing · Issues · Release notes · Resource budgets

For conversational queries over recorded MCP executions, see SpanHound.

Upgrading from Agent Observatory

Agenturm is the new name. Existing Python imports (observatory), OBSERVATORY_* settings, telemetry keys, and observatory.db history remain supported. Use the agenturm executable.

Metadata

Release files for agenturm 0.2.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agenturm 0.2.4
File Size Uploaded Provenance Actions
agenturm-0.2.4.tar.gz 851.5 kB With provenance Details for agenturm-0.2.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agenturm 0.2.4
File Interpreter ABI Platform Actions
agenturm-0.2.4-py3-none-any.whl Python 3 none any Details for agenturm-0.2.4-py3-none-any.whl

Total release size: 1.3 MB

Release files / agenturm-0.2.4.tar.gz

Download URL agenturm-0.2.4.tar.gz
Size 851.5 kB
Tags Source
SHA-256 checksum
How to use checksums
9e7843c22f829b7651a33f3ce93c5690e17a4dc55f5dccab8e2de8c2293f7bb5
BLAKE2b-256 checksum
How to use checksums
83cab856e542a8babc59a1852eb64ef4c4f887279a19ddfaf577eda8f280959e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / agenturm-0.2.4-py3-none-any.whl

Download URL agenturm-0.2.4-py3-none-any.whl
Size 492.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
aa3ca2ed81d1ee107786aacadc92362cc0ab02be452ed6d4be2955ba297c2185
BLAKE2b-256 checksum
How to use checksums
93c2551facf3c95232d1cfe8b0f77ede5cd3805e5129053d03ca2fdb914064b5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for agenturm 0.2.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agenturm-0.2.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page