@klars/agentobs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Klars AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# AgentObs
+
+**See every tool call, token, and dollar your AI coding agents spend — and stop them before they do something risky.**
+
+AgentObs is an observability and control layer for AI coding agents. It runs
+entirely on your machine: a CLI, a local SQLite database, and a dashboard. No
+account, no cloud, no telemetry.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)
+
+---
+
+## Quick start
+
+```bash
+npm install -g @klars/agentobs
+agentobs init
+```
+
+`init` prints a hook configuration block. Paste it into `~/.claude/settings.json`
+(or a project's `.claude/settings.json`), then:
+
+```bash
+agentobs dashboard
+```
+
+Run Claude Code as usual. Tool calls appear in the dashboard within seconds.
+
+---
+
+## What you get
+
+|                        |                                                              |
+| ---------------------- | ------------------------------------------------------------ |
+| **Cost tracking**      | Per session, per tool, per day — or blank if the model's price is unknown. Never guessed. |
+| **Tool-call timeline** | Every call, its duration, status, and truncated input.        |
+| **Guardrails**         | Block `rm -rf`, require approval for `.env` edits, stop `curl \| sh`. |
+| **Audit trail**        | Every policy decision recorded with the rule that fired.      |
+| **Any agent**          | Native Claude Code hooks; JSONL ingestion or process-wrapping for everything else. |
+
+---
+
+## Privacy
+
+This is the part that matters most, since AgentObs sits in the middle of
+everything your agent does.
+
+- **Nothing leaves your machine.** No network calls, no analytics, no account.
+- **Secrets are redacted before anything is written to disk.** Tool inputs and
+  outputs pass through a redaction layer that recognises AWS keys, Anthropic /
+  OpenAI / GitHub / GitLab / Slack / Stripe / Google / npm tokens, JWTs, PEM
+  private keys, `KEY=value` assignments, `--flag secret` arguments,
+  `Authorization:` headers, and credentials embedded in URLs.
+- **Summaries are truncated** to ~500 characters.
+- The redaction rules are unit-tested in
+  [`src/core/redact.test.ts`](src/core/redact.test.ts) — the tests are the
+  guarantee, and they have caught real leaks during development.
+
+Everything lives in `~/.agentobs/`. Uninstalling is `rm -rf ~/.agentobs`.
+
+---
+
+## Commands
+
+```
+agentobs init                        Set up ~/.agentobs and print the hook config
+agentobs dashboard [--port] [--host] Serve the dashboard (default 127.0.0.1:4300)
+agentobs stats [--today] [--since]   Print totals in the terminal
+agentobs run -- <command...>         Observe any command (coarse detail)
+agentobs watch <file.jsonl>          Ingest a JSONL agent log
+agentobs export --format csv|json    Export sessions, tool calls, or decisions
+
+agentobs policy init                 Write a starter policy.json
+agentobs policy check                Validate it and list active rules
+agentobs policy test <tool> <input>  Dry-run a call against the policy
+```
+
+---
+
+## Guardrails
+
+`agentobs policy init` writes `~/.agentobs/policy.json`:
+
+```json
+{
+  "rules": [
+    {
+      "name": "no-recursive-force-delete",
+      "match": { "tool": "Bash", "command_pattern": "*rm -rf*" },
+      "decision": "block",
+      "message": "Recursive force-delete is blocked by AgentObs policy."
+    },
+    {
+      "name": "protect-env-files",
+      "match": { "tool": "*", "path_pattern": "**/.env*" },
+      "decision": "needs_approval"
+    }
+  ],
+  "default_decision": "allow"
+}
+```
+
+Rules are evaluated top to bottom; **the first match wins**, so you can put a
+narrow `allow` above a broad `block`. Check what a rule will do *before* it
+fires mid-task:
+
+```bash
+$ agentobs policy test Bash "rm -rf ./build"
+
+  Tool       Bash
+  Input      rm -rf ./build
+  Decision   BLOCK
+  Rule       no-recursive-force-delete
+
+  This call would be BLOCKED before running.
+```
+
+Two deliberate behaviours worth knowing:
+
+- **`needs_approval` currently behaves as a block** with a clearer message.
+  There is no channel for a hook to prompt you interactively mid-call.
+- **A broken policy file fails open.** Invalid JSON or a malformed rule
+  degrades to allow-everything and reports the problem, because a guardrail
+  that wedges your agent is worse than no guardrail. Run `agentobs policy check`.
+
+---
+
+## Agent support
+
+| Agent           | How                        | Detail                                            |
+| --------------- | -------------------------- | ------------------------------------------------- |
+| **Claude Code** | Native hooks               | **Rich** — every tool call, plus policy enforcement |
+| Any CLI agent   | `agentobs run -- <cmd>`    | **Coarse** — duration and exit code only          |
+| Custom / in-house | `agentobs watch <file>`  | **Rich**, if it writes JSONL                      |
+
+The dashboard labels coarse sessions as `coarse` rather than implying detail it
+does not have.
+
+### A note on cost accuracy
+
+Claude Code's `PostToolUse` hook payload carries **no token or cost fields**.
+AgentObs therefore reads token usage from the session transcript at
+`SessionEnd`, which makes **session-level cost accurate** but leaves
+**per-tool-call cost blank** for hook-sourced data. It does not divide a total
+across calls to manufacture a number.
+
+Model prices live in `~/.agentobs/pricing.json` and are yours to edit. A model
+missing from that file shows cost as `—`, never `$0.00`.
+
+---
+
+## Dashboard access
+
+Binds to `127.0.0.1` with no authentication — same machine, same user, same
+trust boundary as the database file.
+
+Binding anywhere else **requires a token**, printed at startup and included in
+the URL:
+
+```bash
+agentobs dashboard --host 0.0.0.0
+```
+
+**Never expose the dashboard to the public internet.** It shows tool inputs and
+file paths from your repositories.
+
+---
+
+## Requirements
+
+Node.js **≥ 22.5** — AgentObs uses the built-in `node:sqlite` module, so there
+is no native addon to compile and no C++ toolchain to install.
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+Adding an adapter for another agent: see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT © [Klars AI](https://klars.ai)

package/bin/agentobs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from '../dist/cli.js';
+main(process.argv).catch((err) => {
+  console.error(err?.message ?? err);
+  process.exit(1);
+});

package/bin/agentobs-hook

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Claude Code invokes this once per hook event with JSON on stdin. It must
+// never fail in a way that blocks the agent, so main() already swallows
+// everything; this outer catch is the last resort.
+import { main } from '../dist/adapters/claude-code-hook.js';
+main().catch(() => process.exit(0));

package/dist/adapters/claude-code-hook.js

@@ -0,0 +1,204 @@
+/**
+ * Claude Code hook adapter - the `agentobs-hook` entrypoint.
+ *
+ * Claude Code invokes this once per hook event with the event JSON on stdin.
+ * It does two jobs in one process: record the call (observability) and, for
+ * PreToolUse, evaluate the policy and return a decision (enforcement).
+ *
+ * Contract verified against Claude Code's hooks reference:
+ *
+ *  - Payload fields are snake_case: `session_id`, `tool_name`, `tool_input`,
+ *    `tool_use_id`, `hook_event_name`, `cwd`, `transcript_path`.
+ *  - PreToolUse blocks via `hookSpecificOutput.permissionDecision: "deny"`
+ *    printed to stdout with exit code 0. Exit code 2 also blocks, but the
+ *    JSON form is used here because it carries a reason string back to both
+ *    the user and the agent. JSON is only honoured on exit 0.
+ *  - PostToolUse carries NO token or cost fields. Per-call cost therefore
+ *    cannot come from the hook; see transcript.ts, which reads the usage
+ *    numbers Claude Code writes to its own transcript. Nothing here ever
+ *    invents a token count.
+ *  - SessionEnd hooks share a ~1.5s budget, so this must stay fast.
+ *
+ * Failure posture: this process sits in front of every tool call the user's
+ * agent makes. Any unexpected error must exit 0 with no decision, letting the
+ * call proceed - a crashed observability tool must never wedge the agent.
+ */
+import { randomUUID } from 'node:crypto';
+import { appendFileSync } from 'node:fs';
+import { openDb } from '../core/db.js';
+import { ensureHome, paths } from '../core/paths.js';
+import { beginToolCall, completeToolCall, endSession, ensureSession, recordPolicyDecision, startSession, } from '../core/repo.js';
+import { contextFromToolInput, evaluate, loadPolicy } from '../core/policy-engine.js';
+import { attachTranscriptUsage } from './transcript.js';
+const AGENT_NAME = 'claude-code';
+/**
+ * Deterministic tool-call id derived from Claude Code's own `tool_use_id`.
+ *
+ * PreToolUse and PostToolUse arrive as separate processes, so the pair has to
+ * agree on an id without sharing memory. Using the agent's id makes that
+ * automatic; the random fallback only applies when it's absent, in which case
+ * the two halves simply won't be joined (better than mis-joining them).
+ */
+function toolCallId(payload) {
+    return payload.tool_use_id ?? randomUUID();
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => (data += chunk));
+        process.stdin.on('end', () => resolve(data));
+        // A hook with no stdin should not hang the agent forever.
+        process.stdin.on('error', () => resolve(data));
+    });
+}
+/** Diagnostic log. Never throws - logging must not break the hook. */
+function debugLog(message) {
+    if (!process.env.AGENTOBS_DEBUG)
+        return;
+    try {
+        ensureHome();
+        appendFileSync(paths.hookLog(), `${new Date().toISOString()} ${message}\n`);
+    }
+    catch {
+        /* ignore */
+    }
+}
+export function handleHook(payload) {
+    const event = payload.hook_event_name;
+    const sessionId = payload.session_id ?? 'unknown-session';
+    const db = openDb();
+    switch (event) {
+        case 'SessionStart': {
+            startSession(db, {
+                id: sessionId,
+                agentName: AGENT_NAME,
+                cwd: payload.cwd ?? null,
+                fidelity: 'rich',
+            });
+            return { exitCode: 0 };
+        }
+        case 'SessionEnd': {
+            // Backfill token usage from the transcript before closing out: this is
+            // the only place Claude Code exposes real usage numbers, and the
+            // session is complete by now so the file is final.
+            if (payload.transcript_path) {
+                try {
+                    attachTranscriptUsage(db, sessionId, payload.transcript_path);
+                }
+                catch (err) {
+                    debugLog(`transcript backfill failed: ${String(err)}`);
+                }
+            }
+            endSession(db, sessionId);
+            return { exitCode: 0 };
+        }
+        case 'PreToolUse': {
+            const toolName = payload.tool_name ?? 'unknown';
+            const id = toolCallId(payload);
+            ensureSession(db, sessionId, AGENT_NAME, payload.cwd ?? null);
+            const { policy, errors } = loadPolicy();
+            for (const err of errors)
+                debugLog(`policy: ${err}`);
+            const verdict = evaluate(policy, contextFromToolInput(toolName, payload.tool_input));
+            if (verdict.decision === 'allow') {
+                beginToolCall(db, {
+                    id,
+                    sessionId,
+                    toolName,
+                    input: payload.tool_input,
+                    status: 'pending',
+                });
+                // No JSON output: fall through to Claude Code's normal permission
+                // flow rather than force-allowing something the user's own settings
+                // would have prompted about.
+                return { exitCode: 0 };
+            }
+            // Blocked, or needs approval - which v1 treats as a block with a
+            // clearer message, since there is no interactive approval channel from
+            // inside a hook.
+            beginToolCall(db, {
+                id,
+                sessionId,
+                toolName,
+                input: payload.tool_input,
+                status: 'blocked',
+            });
+            recordPolicyDecision(db, {
+                toolCallId: id,
+                sessionId,
+                toolName,
+                ruleMatched: verdict.rule?.name ?? null,
+                decision: verdict.decision,
+                reason: verdict.message,
+            });
+            const reason = verdict.decision === 'needs_approval'
+                ? `${verdict.message} This needs your approval: edit ~/.agentobs/policy.json or run "agentobs policy test ${toolName} <input>" to check the rule.`
+                : `${verdict.message} (AgentObs rule: ${verdict.rule?.name ?? 'unnamed'})`;
+            return {
+                stdout: JSON.stringify({
+                    hookSpecificOutput: {
+                        hookEventName: 'PreToolUse',
+                        permissionDecision: 'deny',
+                        permissionDecisionReason: reason,
+                    },
+                }),
+                exitCode: 0,
+            };
+        }
+        case 'PostToolUse': {
+            const id = toolCallId(payload);
+            const result = payload.tool_response ?? payload.tool_result;
+            const errorMessage = extractError(result);
+            completeToolCall(db, id, {
+                status: errorMessage ? 'error' : 'success',
+                output: result,
+                errorMessage,
+                // Deliberately no token counts: PostToolUse does not carry them, and
+                // inventing a number would poison the cost figure this tool exists
+                // to report. transcript.ts fills these in from the real transcript.
+            });
+            return { exitCode: 0 };
+        }
+        default:
+            debugLog(`ignoring unknown hook event: ${event}`);
+            return { exitCode: 0 };
+    }
+}
+/** Pulls an error message out of a tool result, if it reads like a failure. */
+function extractError(result) {
+    if (!result)
+        return null;
+    if (typeof result === 'string') {
+        return /^(error|exception|traceback)\b/i.test(result.trim()) ? result : null;
+    }
+    if (typeof result === 'object') {
+        const obj = result;
+        if (obj.is_error === true || obj.isError === true) {
+            return typeof obj.content === 'string' ? obj.content : JSON.stringify(obj).slice(0, 300);
+        }
+        if (typeof obj.error === 'string' && obj.error)
+            return obj.error;
+    }
+    return null;
+}
+/** Process entrypoint for bin/agentobs-hook. */
+export async function main() {
+    let result = { exitCode: 0 };
+    try {
+        const raw = await readStdin();
+        if (raw.trim()) {
+            result = handleHook(JSON.parse(raw));
+        }
+    }
+    catch (err) {
+        // Fail open, always. A hook that throws would surface inside the user's
+        // agent as a tool failure caused by their monitoring tool.
+        debugLog(`hook error: ${String(err)}`);
+        result = { exitCode: 0 };
+    }
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    process.exit(result.exitCode);
+}
+//# sourceMappingURL=claude-code-hook.js.map

package/dist/adapters/jsonl-watcher.js

@@ -0,0 +1,185 @@
+/**
+ * Generic JSONL adapter: `agentobs watch <file>`.
+ *
+ * Tails a newline-delimited JSON log and maps each line to an AgentEvent.
+ * This is the integration path for any agent that can be made to write a
+ * structured log but has no hook system, and it is also how a user can pipe
+ * a custom or in-house agent into AgentObs without writing TypeScript.
+ *
+ * Field names are matched leniently (snake_case and camelCase, several
+ * common aliases) because the whole point is ingesting logs this project
+ * does not control.
+ */
+import { createReadStream, existsSync, statSync, watch } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { randomUUID } from 'node:crypto';
+import { createSink } from './sink.js';
+const str = (row, ...keys) => {
+    for (const k of keys) {
+        const v = row[k];
+        if (typeof v === 'string' && v)
+            return v;
+    }
+    return null;
+};
+const num = (row, ...keys) => {
+    for (const k of keys) {
+        const v = row[k];
+        if (typeof v === 'number' && Number.isFinite(v))
+            return v;
+    }
+    return null;
+};
+/**
+ * Maps one JSONL row to an AgentEvent, or null if it isn't one we recognise.
+ *
+ * Unrecognised lines are skipped silently rather than treated as errors: a
+ * real agent log interleaves many record types, and warning on each would
+ * bury the user in noise for lines that are simply not ours.
+ */
+export function parseLine(line, fallbackSession, agentName) {
+    let row;
+    try {
+        row = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!row || typeof row !== 'object')
+        return null;
+    const type = str(row, 'type', 'event', 'event_type', 'eventType');
+    const sessionId = str(row, 'session_id', 'sessionId', 'session') ?? fallbackSession;
+    const timestamp = str(row, 'timestamp', 'time', 'ts', 'started_at') ?? undefined;
+    switch (type) {
+        case 'session_start':
+        case 'session-start':
+        case 'start':
+            return {
+                type: 'session_start',
+                sessionId,
+                agentName: str(row, 'agent', 'agent_name', 'agentName') ?? agentName,
+                cwd: str(row, 'cwd', 'working_dir', 'workingDirectory'),
+                fidelity: 'rich',
+                timestamp,
+            };
+        case 'session_end':
+        case 'session-end':
+        case 'end':
+            return {
+                type: 'session_end',
+                sessionId,
+                exitCode: num(row, 'exit_code', 'exitCode'),
+                timestamp,
+            };
+        case 'tool_call':
+        case 'tool_use':
+        case 'tool': {
+            // A single complete tool-call record: synthesise the start/end pair so
+            // downstream code only ever deals with one shape.
+            const id = str(row, 'id', 'tool_call_id', 'toolCallId') ?? randomUUID();
+            return {
+                type: 'tool_call_start',
+                sessionId,
+                toolCallId: id,
+                toolName: str(row, 'tool', 'tool_name', 'toolName', 'name') ?? 'unknown',
+                input: row.input ?? row.tool_input ?? row.arguments ?? null,
+                model: str(row, 'model'),
+                timestamp,
+            };
+        }
+        case 'tool_call_start':
+        case 'tool_start':
+            return {
+                type: 'tool_call_start',
+                sessionId,
+                toolCallId: str(row, 'id', 'tool_call_id', 'toolCallId') ?? randomUUID(),
+                toolName: str(row, 'tool', 'tool_name', 'toolName', 'name') ?? 'unknown',
+                input: row.input ?? row.tool_input ?? row.arguments ?? null,
+                model: str(row, 'model'),
+                timestamp,
+            };
+        case 'tool_call_end':
+        case 'tool_end':
+        case 'tool_result': {
+            const status = str(row, 'status', 'result');
+            return {
+                type: 'tool_call_end',
+                toolCallId: str(row, 'id', 'tool_call_id', 'toolCallId') ?? '',
+                status: status === 'error' || row.error ? 'error' : 'success',
+                output: row.output ?? row.result ?? row.tool_response ?? null,
+                tokensIn: num(row, 'tokens_in', 'tokensIn', 'input_tokens', 'prompt_tokens'),
+                tokensOut: num(row, 'tokens_out', 'tokensOut', 'output_tokens', 'completion_tokens'),
+                model: str(row, 'model'),
+                errorMessage: str(row, 'error', 'error_message', 'errorMessage'),
+                timestamp,
+            };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Tails a JSONL file, feeding parsed events into the local database.
+ *
+ * Tracks a byte offset and re-reads only what was appended. A file that
+ * shrinks is treated as truncated/rotated and re-read from zero, which is
+ * the behaviour a user expects from `tail -F` and avoids silently emitting
+ * garbage from a stale offset.
+ */
+export async function watchJsonl(file, opts = {}) {
+    const agentName = opts.agentName ?? 'generic';
+    const follow = opts.follow ?? true;
+    const sink = createSink(agentName);
+    const fallbackSession = randomUUID();
+    if (!existsSync(file))
+        throw new Error(`file not found: ${file}`);
+    let offset = opts.fromStart === false ? statSync(file).size : 0;
+    let reading = false;
+    const drain = async () => {
+        if (reading)
+            return; // a watch event during a read would double-process
+        reading = true;
+        try {
+            const size = statSync(file).size;
+            if (size < offset)
+                offset = 0; // truncated or rotated
+            if (size === offset)
+                return;
+            const stream = createReadStream(file, { start: offset, encoding: 'utf8' });
+            const rl = createInterface({ input: stream, crlfDelay: Infinity });
+            for await (const line of rl) {
+                if (!line.trim())
+                    continue;
+                const event = parseLine(line, fallbackSession, agentName);
+                if (event) {
+                    sink(event);
+                    opts.onEvent?.(event);
+                }
+            }
+            offset = size;
+        }
+        finally {
+            reading = false;
+        }
+    };
+    await drain();
+    if (!follow)
+        return;
+    const watcher = watch(file, { persistent: true }, () => {
+        void drain();
+    });
+    // Poll as well as watch: fs.watch misses appends on some filesystems
+    // (network shares, certain Docker mounts) where the tool is likely to be
+    // pointed at a log written by another container.
+    const poll = setInterval(() => void drain(), 2000);
+    await new Promise((resolve) => {
+        const stop = () => {
+            watcher.close();
+            clearInterval(poll);
+            resolve();
+        };
+        process.on('SIGINT', stop);
+        process.on('SIGTERM', stop);
+    });
+}
+//# sourceMappingURL=jsonl-watcher.js.map