codecard

Carbon-style images of code, terminal sessions, diffs and Claude Code transcripts, rendered on your machine and built for agents as well as humans.

Carbon and ray.so are great web UIs for people. But an agent can't click through a web UI, and hosted APIs upload your snippet to someone else's server. codecard is a CLI, an MCP server and a Claude skill that all render locally with headless Chrome. Your code and session logs never leave the laptop, and secrets are masked by default.

Agent transcripts. Turn the last turn of a Claude Code session into one image, drawn in Claude Code's own style (this one is rendered from docs/examples/demo-session.jsonl):

Animated. Add --gif and the lines appear one at a time:

Install

Needs Python 3.10+ and Chrome, Chromium, Edge or Brave (set CODECARD_CHROME=/path/to/binary if it isn't found automatically).

# CLI only
uv tool install git+https://github.com/PuvaanRaaj/codecard

# CLI + MCP server
uv tool install "codecard[mcp] @ git+https://github.com/PuvaanRaaj/codecard"

pipx install "codecard[mcp] @ git+https://github.com/PuvaanRaaj/codecard" works too.

Related MCP server: code-shot

Use it from the command line

codecard code src/app.py -o app.png                  # syntax-highlighted source (language from the filename)
codecard term session.txt -o cmds.png                 # $ commands, output, # comments
codecard term session.txt -o cmds.gif --gif           # the same, animated
git diff HEAD~1 | codecard diff -o change.png         # +/- coloured diff
codecard transcript -n 1 -o turn.png                  # last turn of the newest Claude Code session in this directory

Every kind reads a file or stdin and prints the path it wrote.

Terminal input format: lines starting $ or > are commands, # starts a comment, and everything else is output. A command that runs over several lines ending in \ keeps its colours on every line.

Transcripts: codecard transcript with no argument picks the newest session for the current directory. It searches ~/.claude and any ~/.claude-* config dirs, and respects CLAUDE_CONFIG_DIR. Pass a session id (or its first few characters) or a .jsonl path to choose a different one.

MCP server

Install with the mcp extra (above). That gives you a codecard-mcp command that speaks MCP over stdio.

Claude Code

claude mcp add -s user codecard -- codecard-mcp

Choose where images go with -e CODECARD_OUT=~/Pictures/codecard (default: $TMPDIR/codecard).

Claude Desktop / Cursor / any MCP client

{
  "mcpServers": {
    "codecard": {
      "command": "codecard-mcp",
      "env": { "CODECARD_OUT": "/Users/you/Pictures/codecard" }
    }
  }
}

Claude Desktop reads this from claude_desktop_config.json, and Cursor from ~/.cursor/mcp.json. If the client can't find codecard-mcp on its PATH, use the full path (which codecard-mcp).

Tools

Each tool returns the file path, and for PNGs the image itself, so the model can check its own output. MCP tools always redact; agents can't switch it off. out must end in .png or .gif.

Claude skill

The skill teaches Claude when to reach for codecard ("make an image of this", "carbon this", "gif of this terminal") and how to use it well: short cards, view the result before handing it over, never skip redaction for anything shared. It uses the CLI, so install that first.

git clone https://github.com/PuvaanRaaj/codecard ~/codecard
mkdir -p ~/.claude/skills
ln -s ~/codecard/skill ~/.claude/skills/codecard     # or: cp -r ~/codecard/skill ~/.claude/skills/codecard

To share it with a team through a repo, put it in the project's .claude/skills/codecard/ instead. The skill and the MCP server work fine together or separately.

Safety

• Redaction is on by default, before anything is drawn. It masks GitLab, GitHub, Anthropic, Slack and AWS tokens, bearer tokens, JWTs, private-key blocks, *TOKEN*= / *PASSWORD*:-style assignments, and Luhn-valid card numbers (masked to first 6 / last 4). Your home directory is shown as ~.

• Transcripts never include thinking blocks, subagent sidechains, meta lines or injected <system-reminder> text. They do include your prompts and tool output, so look at the image before you share it.

• Redaction matches common formats. It won't catch every secret, and it can't know that a hostname or customer name is internal. Treat it as a seatbelt, not a guarantee.

• Nothing is uploaded. Chrome runs headless against a temporary local HTML file.

How it works

Input → rows of styled tokens (lexers.py, transcript.py) → wrapped to --cols → an HTML card whose height is calculated rather than measured (render.py) → one headless-Chrome screenshot. GIFs are built from that single screenshot with Pillow by painting over the rows not yet shown, so an animation still costs only one Chrome launch.

Development

git clone https://github.com/PuvaanRaaj/codecard && cd codecard
uv sync --extra mcp
uv run --group dev --extra mcp pytest -q

The tests include rendering through a real Chrome and driving the MCP server over real stdio JSON-RPC. Both are skipped automatically if Chrome isn't installed.

License

MIT