Skip to content
Back to search

tma1

MarketplaceWorks with Claude CodeGitHub

Local-first observability your agent reads back. TMA1 records every LLM call, then routes what it sees into the agent's next turn via hooks and MCP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tma1-ai/tma1 with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tma1-ai/tma1'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tma1-ai--tma1/badge.svg)](/listings/tma1-ai--tma1)

HTML

<a href="/listings/tma1-ai--tma1"><img src="/api/listings/tma1-ai--tma1/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

curl -fsSL https://tma1.ai/install.sh | TMA1_ADAPTER=claude-code bash

The installer registers TMA1 as a background service and starts it. The dashboard is at <http://localhost:14318>.

`TMA1_ADAPTER` accepts `claude-code`, `codex`, or `all`. See [Install](#install) for Windows and for installing without an adapter.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 11 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "tma1",
  3. "owner": { "name": "killme2008" },
  4. "plugins": [
  5. {
  6. "name": "tma1",
  7. "source": "./claude-plugin",
  8. "description": "Local-first LLM agent observability. Track tokens, cost, and conversations on your machine."
  9. }
  10. ]
  11. }
README.md · README · 383 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # TMA1
  2. <!-- include_prereleases is required: every TMA1 release so far is a
  3. pre-release, and without it the badge renders "no releases found".
  4. Leave sort at the default (date) — semver sort compares the
  5. pre-release identifier lexically, which orders alpha9 above alpha14. -->
  6. [![Release](https://img.shields.io/github/v/release/tma1-ai/tma1?include_prereleases&label=release&color=orange)](https://github.com/tma1-ai/tma1/releases)
  7. [![CI](https://github.com/tma1-ai/tma1/actions/workflows/ci.yml/badge.svg)](https://github.com/tma1-ai/tma1/actions/workflows/ci.yml)
  8. [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
  9. ![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)
  10. > A monolith for your agent's loop. Silent until it talks back.
  11. TMA1 is local-first observability for LLM agents, powered by GreptimeDB.
  12. It records every LLM call on your machine, then routes what it sees back
  13. into the agent's next turn through hooks and MCP tools.
  14. One binary. No Docker. No Grafana. No cloud account.
  15. ![TMA1 Dashboard](site/public/screenshots/hero-dark.webp)
  16. The name comes from TMA-1 (Tycho Magnetic Anomaly-1) in *2001: A Space
  17. Odyssey*: the monolith buried on the moon, silently recording everything
  18. until you dig it out.
  19. ## Quickstart
  20. ```bash
  21. curl -fsSL https://tma1.ai/install.sh | TMA1_ADAPTER=claude-code bash
  22. ```
  23. The installer registers TMA1 as a background service and starts it. The
  24. dashboard is at <http://localhost:14318>.
  25. `TMA1_ADAPTER` accepts `claude-code`, `codex`, or `all`. See
  26. [Install](#install) for Windows and for installing without an adapter.
  27. ## What it does
  28. TMA1 does two things.
  29. It feeds context to the agent. Before each turn the agent receives a
  30. `<tma1-context>` block: what it has done this session, which files changed
  31. under it, whether the build is broken, and any anomaly worth acting on.
  32. Current anomaly rules provide advisory context and do not block the `Stop`
  33. hook. Ten MCP tools answer further queries on demand, including
  34. keyword search across every session recorded on the machine.
  35. It reports to you. The dashboard covers token usage, cost, latency,
  36. tool activity, conversation replay, anomaly history, prompt evaluation,
  37. and SQL over the raw tables.
  38. The Overview page combines activity across agents, recent sessions, and
  39. recorded tool failures. Sessions supports side-by-side comparison of two
  40. sessions: reported tokens, cache read share, tool failures, and compaction
  41. events. Missing usage is shown as unavailable. Input tokens include cache;
  42. output tokens include reasoning. Elapsed span includes idle time.
  43. Prompts lists requests without keyword-based scores. On-demand model reviews
  44. send the selected request and bounded conversation excerpts to the configured
  45. provider. Suggestions include source quotes, an impact, and a concrete action,
  46. separating request gaps from agent execution. The model can abstain when context
  47. is missing. AI Insights summarizes a text-only sample, not task outcomes.
  48. Cost estimates use API list prices checked on 2026-10-30, including cache
  49. reads, cache writes by duration, and OpenAI Fast mode (`service_tier`
  50. `priority`). Unknown models show no estimate. A request stays unpriced when its
  51. service tier, its cache-write duration, or a price it needs is unavailable, or
  52. when its prompt exceeds the short-context limit (272K tokens for OpenAI models,
  53. 200K for Claude Sonnet 4 and 4.5). Claude Code and Codex transcripts record the
  54. tier and write duration from this version on; earlier transcript usage stays
  55. unpriced. GenAI trace aggregates show the uncached standard-tier list-rate
  56. equivalent. Estimates exclude subscription plans, regional premiums, batch and
  57. flex pricing, and historical price changes.
  58. ## Supported sources
  59. | Source | How TMA1 reads it | What you get |
  60. |--------|-------------------|--------------|
  61. | Claude Code | OTel metrics/logs/traces, hooks, JSONL transcripts | Cost, tools, traces, sessions, anomalies, injected context |
  62. | Codex | OTel logs/metrics, hooks, JSONL sessions | Cost, tools, sessions, anomalies, injected context |
  63. | Copilot CLI | JSONL sessions from `~/.copilot/session-state/` | Sessions, tools, cost where available |
  64. | [OpenCode](docs/opencode.md) | Official v1 session export or idle-event plugin | Sessions, prompts, tools, normalized token usage |
  65. | Any GenAI app | OTel traces using GenAI semantic conventions | Traces, latency, cost aggregation |
  66. All data is stored locally under `~/.tma1/`.
  67. ## How it fits together
  68. ```text
  69. Agent -- OTLP/HTTP --+
  70. -- /api/hooks +--> tma1-server (port 14318)
  71. -- MCP stdio --+ |
  72. v
  73. GreptimeDB (port 14000)
  74. |
  75. v
  76. Embedded dashboard
  77. ```
  78. TMA1 reverse-proxies OTLP to GreptimeDB, ingests hook events and JSONL
  79. transcripts, runs the perception layer, stores everything in GreptimeDB, and
  80. serves the dashboard.
  81. Traces, metrics, and logs are kept as queryable data. Session data and
  82. anomaly emits live in `tma1_*` tables.
  83. Four query surfaces: the TMA1 dashboard, the `exec_query` MCP tool,
  84. MySQL protocol on port `14002`, and GreptimeDB's own dashboard
  85. (SQL/PromQL editor, table browser) at
  86. <http://localhost:14000/dashboard/#/dashboard/query>.
  87. ## Closing the agent loop
  88. TMA1 pushes and pulls context.
  89. Hooks push context into the next agent turn. The installer registers all
  90. 27 Claude Code hook events for telemetry, but only five of them inject
  91. anything back: `SessionStart`, `UserPromptSubmit`, `PostToolUse`, `Stop`,
  92. and `PreCompact`. Codex registers five and injects on four; it has no
  93. `PreCompact`, and it ignores `additionalContext` from `PreToolUse`, so
  94. that one is telemetry only.
  95. The hook script POSTs to `http://127.0.0.1:14318/api/hooks`; the response
  96. body becomes agent context. When TMA1 is unreachable or slow the hook
  97. returns empty stdout and the agent continues without it.
  98. MCP serves the pull direction, from the same binary:
  99. ```bash
  100. tma1-server mcp-serve
  101. ```
  102. It exposes:
  103. | Tool | Purpose |
  104. |------|---------|
  105. | `get_context_bundle` | One compact view of session state, anomalies, build status, external changes, and project structure |
  106. | `get_session_state` | Tool history, token totals, current focus, recent files |
  107. | `get_anomalies` | Active anomalies for the session |
  108. | `get_build_status` | Last captured build/dev output |
  109. | `get_external_changes` | Files changed outside the agent loop |
  110. | `get_project_state` | Cached project language, build system, key files, top-level dirs |
  111. | `get_peer_sessions` | Recent sessions on this project by agent — peers, or your own with `agent_source: "self"` |
  112. | `search_sessions` | Find past sessions by what was said in them |
  113. | `get_session_transcript` | Read one session's conversation, by id or id prefix |
  114. | `exec_query` | One read-only `SELECT` against the local database |
  115. `/tma1-peer codex` wraps `get_peer_sessions`: Claude Code reads Codex's
  116. work on the same project verbatim. The Codex-side skill does the reverse.
  117. ## Session history
  118. Every session from every agent on the machine is stored locally and stays
  119. queryable, by you in the dashboard and by the agent through MCP:
  120. ```
  121. /tma1-search retry backoff # which past sessions discussed this?
  122. /tma1-search --session 3d8f1d0a # read that session's conversation
  123. /tma1-peer self --limit 3 # what did I do here earlier today?
  124. ```
  125. `search_sessions` scopes to the current project by default and returns
  126. matching sessions with snippets and a `session_id`. `--all-projects`
  127. widens the scope; `--days N` widens the window.
  128. `get_session_transcript` accepts that id, or the 8-character abbreviation
  129. from the `<tma1-context>` block, and pages through the conversation with
  130. `offset` / `has_more`.
  131. Keyword matching runs against a FULLTEXT index and is word-boundary based
  132. and case-sensitive. When that pass returns nothing, the search widens to a
  133. case-folded substring scan and reports `match_mode: "substring"`.
  134. ## Install
  135. `TMA1_ADAPTER` wires a coding agent's hooks, MCP entry, and skills.
  136. Claude Code and Codex require it for context injection and the `/tma1-*`
  137. commands. It is optional otherwise: OTLP traffic to port 14318 is
  138. recorded without it, and Copilot CLI sessions are discovered from disk.
  139. ```bash
  140. # macOS / Linux
  141. curl -fsSL https://tma1.ai/install.sh | TMA1_ADAPTER=claude-code bash
  142. curl -fsSL https://tma1.ai/install.sh | TMA1_ADAPTER=codex bash
  143. curl -fsSL https://tma1.ai/install.sh | TMA1_ADAPTER=all bash
  144. # no adapter — server only, wire an agent later
  145. curl -fsSL https://tma1.ai/install.sh | bash
  146. ```
  147. Windows PowerShell, with the adapter as an environment variable:
  148. ```powershell
  149. $env:TMA1_ADAPTER = 'claude-code'; irm https://tma1.ai/install.ps1 | iex
  150. ```
  151. The installer registers a background service (launchd agent on macOS,
  152. systemd user unit on Linux, scheduled task on Windows) and starts it. The
  153. dashboard is available at <http://localhost:14318> when the script exits.
  154. Start `tma1-server` manually only when building from source, or when
  155. service registration was skipped.
  156. On first start TMA1 writes a GreptimeDB config into `~/.tma1/config/`,
  157. downloads the GreptimeDB binary if needed, starts it as a child process,
  158. and serves the dashboard from the same `tma1-server` process.
  159. ## Wire an agent
  160. To have the agent install TMA1 itself:
  161. ```text
  162. Read https://tma1.ai/SKILL.md and follow the instructions to install or upgrade TMA1 for your AI agent
  163. ```
  164. The curl installer writes global files only: hook scripts, MCP config,
  165. and the TMA1 skills. Project-local `AGENTS.md` and `CLAUDE.md` are left
  166. untouched.
  167. Skill and command files are written by `install`, not refreshed by the
  168. binary at startup. Re-run `install --adapter` after upgrading;
  169. `tma1-server` logs a warning at startup when the installed files no
  170. longer match the binary.
  171. For project-local instructions, run from the project root:
  172. ```bash
  173. tma1-server install --adapter claude-code --project .
  174. tma1-server install --adapter codex --project .
  175. ```
  176. Uninstall adapter wiring:
  177. ```bash
  178. tma1-server uninstall --adapter claude-code --project .
  179. tma1-server uninstall --adapter codex --project .
  180. ```
  181. ## Build sensor
  182. The build wrapper captures dev and test output and feeds failures back to
  183. the agent. Two modes:
  184. ```bash
  185. # One-shot — wrapper exits with the wrapped command's exit code:
  186. tma1 build --tag test -- make test
  187. tma1 build --filter-regex '^error|FAIL' -- pytest -v
  188. # Persistent (dev servers, watchers) — use --watch for time-debounced flush
  189. # and Ctrl-C signal forwarding:
  190. tma1 build --watch --tag dev -- npm run dev
  191. tma1 build --watch --tag watch -- cargo watch -x test
  192. ```
  193. The build sensor writes to `tma1_build_events` for build status and error
  194. inspection. Repeated-failure detection uses completed Bash hook events,
  195. grouped by full command and working directory. See [anomaly rules](docs/anomalies.md).
  196. Supported flags:
  197. | Flag | Purpose |
  198. |------|---------|
  199. | `--watch` | Long-running mode: flush on a debounce interval instead of by line count, and forward SIGINT/SIGTERM to the wrapped process. Required for persistent processes like `npm run dev`. |
  200. | `--debounce DUR` | Flush interval for `--watch` (default `2s`) |
  201. | `--tag NAME` | Tag this build run so the dashboard can group it (e.g. `npm`, `pytest`) |
  202. | `--filter-regex PAT` | Only capture lines matching the pattern |
  203. | `--filter-invert` | Invert the filter — capture lines NOT matching the pattern |
  204. | `--no-color` | Strip ANSI color codes from captured output |
  205. | `--project DIR` | Override the project directory used for scoping (default: cwd) |
  206. ## OTLP endpoints
  207. Use the wildcard endpoint when the agent or SDK supports it:
  208. ```text
  209. http://localhost:14318/v1/otlp
  210. ```
  211. Direct signal endpoints are also accepted:
  212. ```text
  213. http://localhost:14318/v1/traces
  214. http://localhost:14318/v1/metrics
  215. http://localhost:14318/v1/logs
  216. ```
  217. Codex commonly uses separate per-signal endpoints; most OTel SDKs can use
  218. the single `/v1/otlp` base.
  219. ## Configuration
  220. | Variable | Default | Description |
  221. |----------|---------|-------------|
  222. | `TMA1_HOST` | `127.0.0.1` | Address `tma1-server` binds to |
  223. | `TMA1_PORT` | `14318` | HTTP port for `tma1-server` |
  224. | `TMA1_DATA_DIR` | `~/.tma1` | Data, config, and binary directory |
  225. | `TMA1_GREPTIMEDB_VERSION` | `v1.3.1` | GreptimeDB version to install. Pinned to an exact tag; set to `latest` to track stable releases instead |
  226. | `TMA1_GREPTIMEDB_HTTP_PORT` | `14000` | GreptimeDB HTTP and OTLP port |
  227. | `TMA1_GREPTIMEDB_GRPC_PORT` | `14001` | GreptimeDB gRPC port |
  228. | `TMA1_GREPTIMEDB_MYSQL_PORT` | `14002` | GreptimeDB MySQL protocol port |
  229. | `TMA1_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error` |
  230. | `TMA1_DATA_TTL` | `60d` | Default TTL for auto-created tables |
  231. | `TMA1_LLM_API_KEY` | empty | API key for optional prompt evaluation |
  232. | `TMA1_LLM_PROVIDER` | `anthropic` | `anthropic` or `openai` |
  233. | `TMA1_LLM_MODEL` | auto | Model override for prompt evaluation |
  234. | `TMA1_QUERY_CONCURRENCY` | `4` | Max concurrent SQL queries from the dashboard |
  235. | `TMA1_ADAPTER` | empty | Install-time adapter list: `claude-code`, `codex`, comma-separated, or `all` |
  236. | `TMA1_MCP_CALLER` | empty | Set by adapter installers. Identifies the calling agent, so `get_peer_sessions` can exclude it from the default fan-out and resolve `agent_source: "self"` |
  237. | `TMA1_DISABLE_INJECTION` | unset | Set to `1` to record hooks but return no injected context |
  238. | `TMA1_ENABLE_FILE_CALLBACK` | unset | Set to `1` to write `.tma1-context.md` for non-MCP agents |
  239. | `TMA1_CONTEXT_PRESSURE_THRESHOLD` | `700000` | Input-token threshold for context-pressure anomalies (~70% of a 1M window). Lower it if your model has a smaller context |
  240. Settings changed in the dashboard are saved to `~/.tma1/settings.json`.
  241. Environment variables take priority.
  242. ## CLI
  243. The installer symlinks `tma1-server` as `tma1`.
  244. | Command | Purpose |
  245. |---------|---------|
  246. | `tma1 install --adapter <name>` | Wire a coding agent into TMA1 (`claude-code`, `codex`) |
  247. | `tma1 uninstall --adapter <name>` | Reverse install for one adapter |
  248. | `tma1 build [--watch] -- <cmd>` | Wrap a build/test command and ship its output into `tma1_build_events` |
  249. | `tma1 mcp-serve` | JSON-RPC MCP stdio server; spawned by agents, not invoked directly |
  250. | `tma1 help [SUB]` | Print top-level usage, or details for a specific subcommand |
  251. | `tma1 version` | Print the tma1-server version |
  252. Every subcommand accepts `-h` / `--help`. Run `tma1 help build` or
  253. `tma1 build --help` for the full flag list and examples.
  254. ## Development
  255. ```bash
  256. make build # Build server/bin/tma1-server
  257. make run # Build and run locally
  258. make dev # Auto-rebuild and restart on server file changes (requires fswatch)
  259. make install # Install dev build to ~/.tma1/bin
  260. make sync-plugin # Mirror plugin skills/commands into embedded server files
  261. make vet # go vet ./cmd/... ./internal/... ./web
  262. make lint # golangci-lint v2
  263. make lint-js # ESLint for dashboard JS
  264. make test # go test -race -count=1
  265. make check # vet + lint + test + lint-js
  266. make build-linux # Cross-compile Linux amd64
  267. make build-windows # Cross-compile Windows amd64
  268. ```
  269. Build from source:
  270. ```bash
  271. git clone https://github.com/tma1-ai/tma1.git
  272. cd tma1
  273. make build
  274. ./server/bin/tma1-server
  275. ```
  276. CI also runs ShellCheck for `site/public/install.sh` and PSScriptAnalyzer
  277. for `site/public/install.ps1`.
  278. ## Docs
  279. - [Architecture](docs/architecture.md): module layout, data flow, tables,
  280. env vars, file index
  281. - [Hooks](docs/hooks.md): hook protocol, adapter registration, uninstall
  282. - [MCP tools](docs/mcp-tools.md): tool schemas and behavior
  283. - [Anomalies](docs/anomalies.md): rules, channels, suppression, validation
  284. Troubleshooting, including the case where no data appears, is covered in
  285. the setup skill: <https://tma1.ai/SKILL.md>
  286. ## Explicitly absent
  287. - No cloud service
  288. - No OTel Collector requirement
  289. - No Grafana dependency
  290. - No memory or RAG system
  291. - No multi-tenant mode
  292. - No authentication; TMA1 is a local-only tool
  293. ## License
  294. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.