{"id":47250066,"url":"https://github.com/tma1-ai/tma1","last_synced_at":"2026-05-31T16:01:00.178Z","repository":{"id":344288590,"uuid":"1180588986","full_name":"tma1-ai/tma1","owner":"tma1-ai","description":"Local-first observability for AI agents, with a built-in dashboard. Cost, sessions, anomalies, and conversation replay — all on your machine.","archived":false,"fork":false,"pushed_at":"2026-05-22T10:44:16.000Z","size":60456,"stargazers_count":85,"open_issues_count":4,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-22T16:43:53.164Z","etag":null,"topics":["agent-observability","ai-agents","claude-code","codex","llm-observability","local-first","logs","metrics","observability","openclaw","opentelemetry","self-hosted","sql","tracing"],"latest_commit_sha":null,"homepage":"https://tma1.ai/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tma1-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-13T07:38:38.000Z","updated_at":"2026-05-16T20:56:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"cbc3b988-989b-4862-8771-09bf9800f6c6","html_url":"https://github.com/tma1-ai/tma1","commit_stats":null,"previous_names":["tma1-ai/tma1"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/tma1-ai/tma1","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tma1-ai%2Ftma1","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tma1-ai%2Ftma1/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tma1-ai%2Ftma1/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tma1-ai%2Ftma1/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tma1-ai","download_url":"https://codeload.github.com/tma1-ai/tma1/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tma1-ai%2Ftma1/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33737692,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-observability","ai-agents","claude-code","codex","llm-observability","local-first","logs","metrics","observability","openclaw","opentelemetry","self-hosted","sql","tracing"],"created_at":"2026-03-14T12:54:17.478Z","updated_at":"2026-05-31T16:01:00.140Z","avatar_url":"https://github.com/tma1-ai.png","language":"JavaScript","funding_links":[],"categories":["LLMOps"],"sub_categories":["LLM Observability \u0026 Tracing"],"readme":"# TMA1\n\n\u003e A monolith for your agent's loop. Silent until it talks back.\n\nTMA1 is local-first observability for LLM agents, powered by GreptimeDB.\nIt records every LLM call on your machine, then routes what it sees back\ninto the agent's next turn through hooks and MCP tools.\n\nOne binary. No Docker. No Grafana. No cloud account.\n\n![TMA1 Dashboard](site/public/screenshots/hero-dark.webp)\n\nThe name comes from TMA-1 (Tycho Magnetic Anomaly-1) in *2001: A Space\nOdyssey*: the monolith buried on the moon, silently recording everything\nuntil you dig it out.\n\n## What TMA1 Does\n\nTMA1 has two jobs:\n\n1. Show the human what happened.\n2. Tell the agent what it should notice before the next step.\n\nThe dashboard gives you token usage, cost, latency, tool activity, full\nconversation replay, anomaly history, prompt evaluation, and SQL access to\nthe underlying data.\n\nThe agent loop gives Claude Code and Codex a compact `\u003ctma1-context\u003e` block\nbefore each turn, can block `Stop` when a HIGH-severity issue is still\nunresolved, and exposes seven MCP tools the agent can call on demand.\n\n## Supported Sources\n\n| Source | How TMA1 reads it | What you get |\n|--------|-------------------|--------------|\n| Claude Code | OTel metrics/logs/traces, hooks, JSONL transcripts | Cost, tools, traces, sessions, anomalies, injected context |\n| Codex | OTel logs/metrics, hooks, JSONL sessions | Cost, tools, sessions, anomalies, injected context |\n| Copilot CLI | JSONL sessions from `~/.copilot/session-state/` | Sessions, tools, cost where available |\n| OpenClaw | OTel traces/metrics, JSONL sessions | Traces, cost, sessions, security signals |\n| Any GenAI app | OTel traces using GenAI semantic conventions | Traces, latency, cost aggregation |\n\nAll data is stored locally under `~/.tma1/`.\n\n## Install\n\nmacOS / Linux:\n\n```bash\ncurl -fsSL https://tma1.ai/install.sh | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://tma1.ai/install.ps1 | iex\n```\n\nStart the server:\n\n```bash\ntma1-server\n```\n\nOpen the dashboard:\n\n```bash\nopen http://localhost:14318\n```\n\nOn first start, TMA1 writes a GreptimeDB config into `~/.tma1/config/`,\ndownloads the GreptimeDB binary if needed, starts it as a child process, and\nserves the dashboard from the same `tma1-server` process.\n\n## Wire An Agent\n\nThe easiest path is to let the agent read the setup skill:\n\n```text\nRead https://tma1.ai/SKILL.md and follow the instructions to install or upgrade TMA1 for your AI agent\n```\n\nTo wire adapters during install:\n\n```bash\n# Claude Code\ncurl -fsSL https://tma1.ai/install.sh | TMA1_ADAPTER=claude-code bash\n\n# Codex\ncurl -fsSL https://tma1.ai/install.sh | TMA1_ADAPTER=codex bash\n\n# Both\ncurl -fsSL https://tma1.ai/install.sh | TMA1_ADAPTER=all bash\n```\n\nThe curl installer writes global files only: hook scripts, MCP config, and\nthe `/tma1-peer` skill. It does not edit project-local `AGENTS.md` or\n`CLAUDE.md`, because curl-pipe can run from any directory.\n\nTo seed project-local instructions, run from the project root:\n\n```bash\ntma1-server install --adapter claude-code --project .\ntma1-server install --adapter codex --project .\n```\n\nUninstall adapter wiring:\n\n```bash\ntma1-server uninstall --adapter claude-code --project .\ntma1-server uninstall --adapter codex --project .\n```\n\n## Closing The Agent Loop\n\nTMA1 pushes and pulls context.\n\n**Hooks push context into the next agent turn.**\n\nClaude Code gets five injection events: `SessionStart`, `UserPromptSubmit`,\n`PostToolUse`, `Stop`, and `PreCompact`. Codex gets the four it supports;\nCodex has no `PreCompact` hook.\n\nThe hook script POSTs to `http://127.0.0.1:14318/api/hooks`. The response\nbody becomes agent context. If TMA1 is down or slow, the hook returns empty\nstdout and lets the agent continue.\n\n**MCP lets the agent ask for context on demand.**\n\nThe MCP server is the same binary:\n\n```bash\ntma1-server mcp-serve\n```\n\nIt exposes:\n\n| Tool | Purpose |\n|------|---------|\n| `get_context_bundle` | One compact view of session state, anomalies, build status, external changes, and project structure |\n| `get_session_state` | Tool history, token totals, current focus, recent files |\n| `get_anomalies` | Active anomalies for the session |\n| `get_build_status` | Last captured build/dev output |\n| `get_external_changes` | Files changed outside the agent loop |\n| `get_project_state` | Cached project language, build system, key files, top-level dirs |\n| `get_peer_sessions` | Recent work left by peer agents on the same project |\n\n`/tma1-peer codex` is a thin skill wrapper around `get_peer_sessions`: it\nlets Claude Code read what Codex just did on the same project, verbatim. The\nCodex-side skill works the other direction.\n\n## How It Fits Together\n\n```text\nAgent -- OTLP/HTTP --+\n       -- /api/hooks +--\u003e tma1-server (port 14318)\n       -- MCP stdio --+        |\n                              v\n                        GreptimeDB (port 14000)\n                              |\n                              v\n                        Embedded dashboard\n```\n\nTMA1 reverse-proxies OTLP to GreptimeDB, ingests hook events and JSONL\ntranscripts, runs the perception layer, stores everything in GreptimeDB, and\nserves the dashboard.\n\nTraces, metrics, and logs are kept as queryable data. Session data and\nanomaly emits live in `tma1_*` tables. You can query through the dashboard,\nthe HTTP SQL API, or MySQL protocol on port `14002`.\n\n## Build Sensor\n\nUse the build wrapper when you want TMA1 to capture dev/test output and feed\nfresh failures back to the agent. Two modes:\n\n```bash\n# One-shot — wrapper exits with the wrapped command's exit code:\ntma1 build --tag test -- make test\ntma1 build --filter-regex '^error|FAIL' -- pytest -v\n\n# Persistent (dev servers, watchers) — use --watch for time-debounced flush\n# and Ctrl-C signal forwarding:\ntma1 build --watch --tag dev -- npm run dev\ntma1 build --watch --tag watch -- cargo watch -x test\n```\n\nThe build sensor writes to `tma1_build_events`. Anomaly rules\n(`repeated_failed_build`, `build_broken_after_my_edit`) read this table\nto tell the agent to stop retrying the same failing command and fix the\ncurrent error first.\n\nSupported flags:\n\n| Flag | Purpose |\n|------|---------|\n| `--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`. |\n| `--debounce DUR` | Flush interval for `--watch` (default `2s`) |\n| `--tag NAME` | Tag this build run so the dashboard can group it (e.g. `npm`, `pytest`) |\n| `--filter-regex PAT` | Only capture lines matching the pattern |\n| `--filter-invert` | Invert the filter — capture lines NOT matching the pattern |\n| `--no-color` | Strip ANSI color codes from captured output |\n| `--project DIR` | Override the project directory used for scoping (default: cwd) |\n\n## OTLP Endpoints\n\nUse the wildcard endpoint when the agent or SDK supports it:\n\n```text\nhttp://localhost:14318/v1/otlp\n```\n\nDirect signal endpoints are also accepted:\n\n```text\nhttp://localhost:14318/v1/traces\nhttp://localhost:14318/v1/metrics\nhttp://localhost:14318/v1/logs\n```\n\nCodex commonly uses separate per-signal endpoints; most OTel SDKs can use\nthe single `/v1/otlp` base.\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TMA1_HOST` | `127.0.0.1` | Address `tma1-server` binds to |\n| `TMA1_PORT` | `14318` | HTTP port for `tma1-server` |\n| `TMA1_DATA_DIR` | `~/.tma1` | Data, config, and binary directory |\n| `TMA1_GREPTIMEDB_VERSION` | `latest` | GreptimeDB version to install |\n| `TMA1_GREPTIMEDB_HTTP_PORT` | `14000` | GreptimeDB HTTP and OTLP port |\n| `TMA1_GREPTIMEDB_GRPC_PORT` | `14001` | GreptimeDB gRPC port |\n| `TMA1_GREPTIMEDB_MYSQL_PORT` | `14002` | GreptimeDB MySQL protocol port |\n| `TMA1_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error` |\n| `TMA1_DATA_TTL` | `60d` | Default TTL for auto-created tables |\n| `TMA1_LLM_API_KEY` | empty | API key for optional prompt evaluation |\n| `TMA1_LLM_PROVIDER` | `anthropic` | `anthropic` or `openai` |\n| `TMA1_LLM_MODEL` | auto | Model override for prompt evaluation |\n| `TMA1_QUERY_CONCURRENCY` | `4` | Max concurrent SQL queries from the dashboard |\n| `TMA1_ADAPTER` | empty | Install-time adapter list: `claude-code`, `codex`, comma-separated, or `all` |\n| `TMA1_MCP_CALLER` | empty | Set by adapter installers so peer-session queries exclude the caller |\n| `TMA1_DISABLE_INJECTION` | unset | Set to `1` to record hooks but return no injected context |\n| `TMA1_ENABLE_FILE_CALLBACK` | unset | Set to `1` to write `.tma1-context.md` for non-MCP agents |\n| `TMA1_CONTEXT_PRESSURE_THRESHOLD` | `100000` | Input-token threshold for context-pressure anomalies |\n| `OPENCLAW_STATE_DIR` | `~/.openclaw` | Override the OpenClaw session directory |\n\nSettings changed in the dashboard are saved to `~/.tma1/settings.json`.\nEnvironment variables take priority.\n\n## CLI\n\nThe `tma1-server` binary (aliased to `tma1` by the installer) is one\nentry point for everything.\n\n| Command | Purpose |\n|---------|---------|\n| `tma1 install --adapter \u003cname\u003e` | Wire a coding agent into TMA1 (`claude-code`, `codex`) |\n| `tma1 uninstall --adapter \u003cname\u003e` | Reverse install for one adapter |\n| `tma1 build [--watch] -- \u003ccmd\u003e` | Wrap a build/test command and ship its output into `tma1_build_events` |\n| `tma1 mcp-serve` | JSON-RPC MCP stdio server (spawned by agents, not run by hand) |\n| `tma1 help [SUB]` | Print top-level usage, or details for a specific subcommand |\n| `tma1 version` | Print the tma1-server version |\n\nEvery subcommand accepts `-h` / `--help`. Run `tma1 help build` or\n`tma1 build --help` for the full flag list and examples.\n\n## Development\n\n```bash\nmake build           # Build server/bin/tma1-server\nmake run             # Build and run locally\nmake dev             # Auto-rebuild and restart on server file changes (requires fswatch)\nmake install         # Install dev build to ~/.tma1/bin\nmake sync-plugin     # Mirror plugin skills/commands into embedded server files\nmake vet             # go vet ./cmd/... ./internal/... ./web\nmake lint            # golangci-lint v2\nmake lint-js         # ESLint for dashboard JS\nmake test            # go test -race -count=1\nmake check           # vet + lint + test + lint-js\nmake build-linux     # Cross-compile Linux amd64\nmake build-windows   # Cross-compile Windows amd64\n```\n\nBuild from source:\n\n```bash\ngit clone https://github.com/tma1-ai/tma1.git\ncd tma1\nmake build\n./server/bin/tma1-server\n```\n\nCI also runs ShellCheck for `site/public/install.sh` and PSScriptAnalyzer\nfor `site/public/install.ps1`.\n\n## Docs\n\n- [Architecture](docs/architecture.md): module layout, data flow, tables,\n  env vars, file index\n- [Hooks](docs/hooks.md): hook protocol, adapter registration, uninstall\n- [MCP tools](docs/mcp-tools.md): tool schemas and behavior\n- [Anomalies](docs/anomalies.md): rules, channels, suppression, validation\n\n## Explicitly Absent\n\n- No cloud service\n- No OTel Collector requirement\n- No Grafana dependency\n- No memory or RAG system\n- No multi-tenant mode\n- No authentication; TMA1 is a local-only tool\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftma1-ai%2Ftma1","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftma1-ai%2Ftma1","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftma1-ai%2Ftma1/lists"}