Claude Code Output Logging with AgentCheck

Claude code output logging matters as soon as agents touch a real repository, shell, or deployment path. If you need to answer basic operational questions like “what tool did the agent call,” “what was blocked,” or “which run wrote this file,” plain terminal transcripts are not enough. You need structured logs, consistent wrapping, and some policy layer that can stop obviously bad behavior before it executes.

That is the problem space AgentCheck targets. It is a behavioral governance layer for Claude Code that wraps each Claude process with hook-based guardrails, logs tool calls to JSONL, and enforces YAML rule packs. The practical value is not branding; it is that claude code output logging becomes machine-readable instead of anecdotal. You can grep it, ship it, diff it across runs, and correlate blocked actions with the rules that caused them.

Why claude code output logging needs structure

Developers usually start by saving terminal output or relying on CI logs. That works for debugging a single failed run, but it falls apart when you want a durable audit trail. Free-form logs do not reliably tell you which tool was invoked, what arguments were passed, whether the action was allowed, or which policy decision changed the result.

Structured JSONL solves a narrow but important problem: one event per line, emitted as the run happens, with enough fields to support indexing and post-processing. That keeps logging cheap and composable. You can pipe it into `jq`, upload it to your log system, or write tests against expected event sequences. For claude code output logging, the important property is not prettiness. It is deterministic structure.

Installing and wrapping Claude Code

AgentCheck installs as a global npm package from GitHub. The wrapper approach is useful because it does not require patching Claude Code itself. Instead, it sits around the process, attaches hooks, and evaluates rule packs before or after relevant actions. That makes it realistic to adopt in a developer workstation or CI runner without rebuilding your whole toolchain.

npm install -g github:paprika-org/agentcheck

# Example workflow:
agentcheck --rules ./rules/repo-safe.yaml --log ./logs/claude-tools.jsonl -- claude

# Example rule pack sketch:
version: 1
rules:
  - id: block-destructive-shell
    match:
      tool: shell
      command_regex: "(rm -rf|git reset --hard)"
    action: deny

  - id: allow-readonly-git
    match:
      tool: shell
      command_regex: "^git (status|diff|show)"
    action: allow

The exact wrapper interface may evolve, but the design is straightforward: start Claude through AgentCheck, point it at a rule pack, and persist logs to a JSONL file. That gives you a repeatable execution boundary. If your team wants different policies for local development versus CI, separate YAML files are a reasonable way to express that without changing application code.

What the logs are good for in practice

The strongest use case is replayable investigation. When an agent does something unexpected, you want more than a screenshot or chat summary. You want a list of tool calls with timestamps, arguments, results, and policy outcomes. That lets you distinguish between three different failures: the model made a bad decision, the environment exposed too much capability, or the rules were too weak.

This is also where claude code output logging becomes useful for teams rather than individuals. JSONL is easy to feed into dashboards or alerting. You can flag patterns like repeated denied shell attempts, writes outside the repo root, or tool usage that drifts over time. None of that requires magical AI observability; it just requires clean events and stable field names.

Rule packs, enforcement, and realistic limitations

YAML rule packs are attractive because they are reviewable and versionable. They fit normal engineering workflows: code review, branch protection, and environment-specific overrides. For governance, that matters more than having a clever policy DSL. A teammate should be able to read a rule and understand what it blocks.

That said, rules are only as good as the hook surface and the patterns you define. Regex-based command matching can miss edge cases. A denied shell command does not help if the dangerous action happens through some other allowed tool. Hook-based systems also depend on the process being launched through the wrapper. If someone runs Claude directly, your policy and logging path may be bypassed.

So the honest positioning is this: AgentCheck improves control and visibility around Claude runs, especially for repositories where you want auditable tool activity. It does not give you complete provenance of everything on the machine, and it does not convert an unsafe execution environment into a safe one by itself.

Troubleshooting common mistakes

The first common mistake is treating logs as complete system truth. If you only log wrapped Claude tool calls, you are not capturing unrelated user actions, background jobs, or post-run cleanup scripts. Keep the scope clear so your incident reviews do not overclaim coverage.

The second mistake is writing permissive rule packs and assuming the log alone is protection. If your policies default to broad shell access and only deny a few obvious commands, the agent may still have enough room to do damage through variants you did not pattern match. Start restrictive, then open capabilities deliberately.

A third practical issue is forgetting log retention and aggregation. A local JSONL file is useful during development, but if you care about history, route it somewhere durable. Otherwise the answer to “what happened last week” becomes “that runner was recycled.”

Frequently Asked Questions

Does AgentCheck capture every Claude Code action?

It captures tool calls and guardrail decisions made through the wrapped Claude process, but it does not magically record activity that happens outside that wrapper or outside the available hooks.

Why use JSONL for logs instead of a single JSON file?

JSONL is append-friendly, streams well, and is easier to process incrementally with shell tools, SIEM pipelines, or batch jobs without rewriting a large document.

Can rule packs prevent dangerous commands?

Yes, that is the point of the YAML rule packs: they can constrain what the agent is allowed to do and block or flag specific classes of actions before they execute.

Is claude code output logging enough for full compliance?

Usually no. It helps create an audit trail for agent behavior, but compliance programs often also require retention controls, identity mapping, access reviews, and downstream log aggregation.