# cc-viewer: watching every Claude Code request as it happens

> cc-viewer is a JavaScript tool that monitors Claude Code, capturing API requests and responses in real time and showing them in a browser so you can review what went into the context. It works as a drop-in replacement for the claude command, and since 1.7.0 it stores logs in a per-session directory format that is roughly 90% smaller on disk than the old single .jsonl files.

**weiesky/cc-viewer** — A request monitoring system for Claude Code that captures and visualizes all API requests and responses in real time. Helps developers monitor their Context for reviewing and debugging during Vibe Coding.

- Repository: https://github.com/weiesky/cc-viewer
- Stars: 1,086 · Forks: 124
- Language: JavaScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/weiesky-cc-viewer

## A wrapper that passes every argument through

The way cc-viewer attaches to Claude Code is the first thing to understand, because it explains why it can capture anything.

ccv is a drop-in replacement for claude. All arguments are passed through to claude while the Web Viewer is launched alongside it.

```bash
ccv                    # == claude (interactive mode)
```

And the README is frank about the invocation it recommends most.

```bash
ccv -c --d             # == claude --continue --dangerously-skip-permissions
                       # ccv passes through every Claude Code launch argument
```

That is the entire interception model. There is no proxy configuration to set and no API key to route through anything, because the tool is a launcher that starts Claude Code itself and reads what the process does. That is also why it can see the requests, and also why it has to know where the claude binary is.

The executable selection is handled in the local page, under Global Settings and Claude executable, and it applies to the CLI, to ccv run -- claude, and to the desktop app. The tool suggests executables found in CodeFuse, on PATH, in npm, and in common native install locations, and you can also type an absolute path or a ~/... path. The choice is saved as claudeExecutablePath in ~/.claude/cc-viewer/preferences.json and takes effect on the next launch.

Two details here are worth reading twice. An explicit selection is authoritative: if it is later missing or not executable, the tool stops with an error instead of silently launching another version, which is the right behaviour when you are auditing what ran. And the tool disables Claude Code's self-updater for the processes it launches, so upgrades stay under the control of the installation you selected.

## Where the logs live, and the v2 format that shrank them

The log format change in 1.7.0 is the most consequential thing in the README, because it changes where your existing data lives.

Since 1.7.0, logs are stored in a per-session directory format, called wire-format v2, instead of single .jsonl files, and the stated saving is roughly 90% smaller on disk.

The migration is careful in a way that suggests the author has had this go wrong. Existing v1 .jsonl files are never modified or deleted. The log dialog lists v2 sessions by default, and a small View legacy (v1) logs entry, shown while old files exist, opens a v1 view where the files can be viewed, migrated, or deleted. On startup the tool offers one-click migration when legacy logs are found, and the README says this is strongly recommended when continuing an old conversation with claude -c, whose first half lives in the old files.

There are commands to do it from the terminal as well.

```bash
ccv convert <project>   # migrate one project
ccv convert --all       # migrate every project
ccv verify <v1-file>    # check a v1 file against its converted sessions
```

And the failure handling is the part worth noting. A session that fails golden verification is held in sessions-quarantine/ for inspection instead of failing the whole migration, and the other sessions still migrate. A migration that stops on one bad file is a migration nobody runs.

The npm package also carries a verify:wire-v2 script, so the format has a machine check behind it rather than only a manual one.

## Logger mode, for when you want to keep the native tool

Not everyone wants to give up the native Claude Code tool or the VS Code extension, and logger mode exists for that case.

In this mode, launching claude will automatically start a logging process that records request logs to per-session directories under ~/.claude/cc-viewer/ and your project name, in the wire-format v2 layout.

```bash
ccv -logger
```

The port handling is described plainly. When the console cannot print a specific port, the default first port is 127.0.0.1:7008, and if multiple instances exist, ports increment sequentially, 7009, 7010 and so on.

The mode is removed with ccv --uninstall.

The reason logger mode exists is worth stating plainly, because it changes what the tool is. The wrapper mode and the logger mode have different footprints on the system. The wrapper replaces the entry point of the tool you were going to use. The logger attaches to a tool you launch yourself, which is a smaller intervention and the right choice if you are working in an environment where the command line for Claude Code is fixed by something else.

The install instructions also warn about mixing package managers. The Homebrew section says to use brew upgrade cc-viewer and not to use npm install -g to upgrade a brew-installed ccv, and the pnpm section says the same. That is a small thing that saves a real confusion, since a globally installed npm package will shadow a brew-installed one on the PATH and the result is a version you did not intend to run.

## SDK mode, where the browser is the terminal

The third mode is the most interesting, because it changes who drives the session.

ccv --sdk runs the session through the Agent SDK instead of an interactive terminal. There is no main PTY, messages are sent from the web UI, and everything else works the same as in terminal mode: session logs, the streaming typewriter, usage stats.

```bash
ccv --sdk                # headless session; chat from the browser
ccv --sdk -c             # continue the most recent session
ccv --sdk --model sonnet # pick a model
```

There is one subtlety the README flags. The header still exposes a Terminal button, but it opens the standalone scratch multi-tab shell, which is unrelated to the SDK session, not a project PTY.

The approval model is the important part for anyone running this against a real repository. Approvals for Bash, Edit, Write and WebFetch pop up in the browser with allow, deny, and allow-for-session, and AskUserQuestion and plan prompts appear as modals. And npm publish always requires an explicit approval, even with --d.

That last rule is a deliberate exception, and it makes sense. The --d flag stands for dangerously-skip-permissions, and the author has decided that publishing a package is never covered by it.

The mode requires the @anthropic-ai/claude-agent-sdk package, which is bundled with cc-viewer, and falls back to terminal mode if it is unavailable. So the fallback is graceful, but it means the feature you are relying on depends on a bundled package rather than on your own Claude Code installation.

## The troubleshooting recipe, which is a joke and also a strategy

The Troubleshooting section is unusual enough to be worth quoting in part, because it tells you how the author thinks about the tool.

The recipe is: open Claude Code in any directory, give Claude Code a specific instruction to check cc-viewer's cli.js and findcc.js and adapt them to the local Claude Code deployment based on the specific environment, keeping the scope of changes confined to findcc.js as much as possible.

And then the claim: letting Claude Code diagnose the problem on its own is more effective than asking anyone or reading any documentation.

That is a joke, but it is also a strategy, and the strategy is the reason the tool has a findcc.js file at all. The hard part of wrapping Claude Code is that its executable location, its installation method and its version all vary between machines, and rather than trying to enumerate every case, the tool discovers the environment at runtime and adapts. Handing that discovery to the model that is already installed is a neat move for a tool whose entire purpose is to sit next to Claude Code.

The follow-up advice is practical. If your project frequently needs local deployment, or your forked code often runs into installation issues, just keep this file and copy it over next time.

The repository layout backs this up. There is a scripts/ directory, a patches/ directory, a homebrew/ directory for the tap, a .changeset/ directory for releases, and a packages/app/ directory holding the server and the CLI, alongside apps/web/ for the browser side and a site/ directory.

## A monorepo with contract checks baked into the test run

The repository is a pnpm monorepo named cc-viewer-monorepo, private, with pnpm@11.22.0 as the package manager and a Node floor of 22.13.0. The README's install instructions ask for nodejs 20.0.0 or newer, which is a discrepancy worth noting before you debug an install failure.

The scripts are the interesting part, because the project treats its own packaging as a contract.

There is a lint:control-bytes check, a verify:boundaries check, a verify:wire-v2 check that runs the CLI's own verify command, a verify:tarball check and a verify:tarball-drift check. And every test entry point runs the same three checks first through a pretest hook, so a broken tarball contract or a boundary violation fails the tests before a single test case runs.

The test command itself sets environment variables that show the test suite is written to be hermetic. CCV_INSTANCE_ID is cleared and CCV_LOG_DIR is set to tmp, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set to 1, and the runner is node --test with --test-force-exit and a two minute timeout, which is the standard Node test runner rather than a framework.

There are separate test targets for the web app, the CLI and coverage, and the build script compiles the web app and then assembles the Node package, with a separate build:sourcemap variant.

The release history is v1.9.6 from 2026-10-15, v1.9.5 from 2026-10-14 and v1.9.4 from 2026-10-12, with the last push on 2026-10-15, so this is a project shipping very often. The licence is MIT, and the README links a feature tour site in 18 languages, along with a native desktop app build on the releases page.

## Conclusion

cc-viewer suits a developer who wants to see what is actually being sent and returned while working with Claude Code, because the request log makes the context visible and reviewable rather than something you infer from the output. It is the wrong tool if you are working on someone else's machine and cannot install a wrapper around the claude executable, and it is the wrong choice if your concern is the data leaving the machine rather than what is in it, since the tool is a monitor and not a filter. Before you adopt it, read the log format section, because the move to the v2 directory format since 1.7.0 changes where your existing sessions live, and decide whether logger mode or the SDK mode fits your workflow, since the SDK mode requires the @anthropic-ai/claude-agent-sdk package and falls back to terminal mode without it.

## FAQ

### What does cc-viewer do?

It is a request monitoring system for Claude Code that captures and visualises API requests and responses in real time, so you can review and debug what is going into the model context during a session.

### How do I install cc-viewer?

With npm install -g cc-viewer, with brew tap weiesky/cc-viewer followed by brew install cc-viewer, or with pnpm add -g cc-viewer. Node 20.0.0 or newer and an existing Claude Code installation are required.

### What is the difference between ccv and claude?

ccv is a drop-in replacement for claude that passes every argument through to Claude Code while launching the web viewer alongside it, so ccv -c --d behaves like claude --continue --dangerously-skip-permissions with the viewer running.

### What changed in cc-viewer 1.7.0?

Logs moved from single .jsonl files to a per-session directory format, wire-format v2, which is roughly 90% smaller on disk. Existing v1 files are never modified or deleted, and ccv convert, ccv convert --all and ccv verify handle migration and checking.

### What is logger mode in cc-viewer?

It is the mode for people who prefer the native claude tool or the VS Code extension. Launching claude then automatically starts a logging process that records request logs to per-session directories under ~/.claude/cc-viewer/ and your project, and it is enabled with ccv -logger and removed with ccv --uninstall.

## Sources

- [Issues](https://github.com/weiesky/cc-viewer/issues)
- [License: MIT](https://github.com/weiesky/cc-viewer/blob/main/LICENSE)
- [README](https://github.com/weiesky/cc-viewer/blob/main/README.md)
- [Releases](https://github.com/weiesky/cc-viewer/releases)
- [weiesky/cc-viewer on GitHub](https://github.com/weiesky/cc-viewer)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/weiesky-cc-viewer