日本語版: README.ja.md
Field notes on how the Claude Code CLI actually behaves, written while running it daily on two macOS machines since early 2026.
These are observation notes, not documentation. Anthropic's docs are the authoritative source for how Claude Code is supposed to work. This repository records what we measured when something did not match expectations — including the cases where our first explanation turned out to be wrong.
Most of these notes started as a debugging session that went sideways. The pattern that kept repeating was: a plausible explanation gets accepted early, work proceeds on top of it, and the real cause is found days later. So each note tries to record two things — what we measured, and which of our own earlier conclusions it killed.
resume-picker.md is the clearest example. An earlier investigation concluded the
session picker had a hardcoded limit of 50. A later re-analysis showed the limit is 200
(current directory) / 500 (all projects) and the real cause of the reported symptom was
a teamName filter hiding entire sessions. The note keeps both, and says which one is
wrong.
Every note carries:
- Verified On — the exact CLI version(s) the observation was made against
- Last Updated — when it was last re-measured, not when it was last edited
If a note is older than the version you are running, treat it as a lead, not a fact. Claude Code ships frequently and several of these behaviours have already changed.
| Note | Subject |
|---|---|
resume-picker.md |
/resume candidate limits and the five filters that hide sessions |
session-storage.md |
Where session JSONL lives and how it is indexed |
binary-versioning.md |
Version directory layout and self-managed symlinks |
backup-system.md |
cleanupPeriodDays semantics and the 0 footgun |
team-system.md / teamName-issue.md |
Agent team lifecycle and the teamName filter |
effort-level-and-launch-pin.md |
/effort levels, settings validation, launch pinning |
env-initialization.md |
Startup environment resolution order |
remote-control-and-oauth.md |
Remote control mode and OAuth session handling |
emoji-width-ghosting.md |
Terminal cell-width mismatches and redraw artifacts |
cc-tui-pane-state-and-mouse.md |
TUI pane state, mouse mode, copy behaviour under tmux |
known-bugs.md |
Reproducible defects, with status |
- Everything here was measured on macOS (arm64). Linux and Windows behaviour is untested and may differ.
- Observations are black-box: what the CLI does, given inputs, observed through its own output, the filesystem, and process state.
- Machine-specific identifiers have been replaced with
host-a/host-b. - Nothing here describes how to circumvent licensing, usage limits, or authentication. Notes covering local machine credential configuration were deliberately excluded.
Bugs found through this work that were filed upstream:
- anthropics/claude-code#78788 — ESC keypresses intermittently dropped under load (tmux + Terminal.app)
Documentation in this repository is released under CC BY 4.0.
Claude Code is a product of Anthropic. This repository is not affiliated with or endorsed by Anthropic.