internalcot

internalcot

[English](README.md) · [简体中文](README.zh-CN.md) **Make agents show their full chain of thought.** internalcot adds an opt-in reasoning workspace to Codex and Claude Code. Turn it on once and the agent must externalize its problem decomposition, intermediate derivation, alternatives, evidence, uncertainty, and checks in the normal tool transcript for the full conversation. ``sh npx internalcot@latest setup ` `text › $internalcot • internalcot mode is active for this conversation. › Recheck this proof. I think the published answer is wrong. • internalcot> Problem: reassess the proof instead of trusting its prior conclusion. Derivation: the required factorials depend on p, so a fixed finite congruence construction does not prove the claim. I need to test any proposed family against the next factorial threshold. Next check: locate the newest claimed proof, then verify that exact gap. ` The result is a persistent, readable chain of thought you can inspect as the agent works. The agent writes its reasoning into visible working notes.

Install

The setup command above installs the CLI and skill together. It detects Codex and Claude Code, shows the exact global command and skill paths, and asks before changing anything. After installation, restart your coding agent if the skill does not appear immediately. For unattended Codex setup: `sh npx internalcot@latest setup --codex --yes ` Use --project to install the skill in the current repository instead of your home directory. Preview every change without applying it: `sh npx internalcot@latest setup --codex --project --dry-run ` Re-running setup updates internalcot's own files and preserves unrelated files in the same skill directory.

Use it

Enable visible working notes: `text $internalcot ` The mode remains active for every response in the current conversation, including across tool calls and context compaction. The agent must record detailed reasoning before its first substantive tool or answer, continue the trace between reasoning phases, and record a final verification before answering. Disable it explicitly: `text $internalcot off ` The mode is conversational state. It does not change the host's native reasoning setting, and a new conversation starts with internalcot off.

What appears in the transcript

A useful note exposes the derivation, not merely a polished goal/check summary: `text internalcot> Goal: find why the refresh token is rejected only after rotation. Constraint: preserve existing session data and do not weaken replay protection. Derivation: rotation updates the token family inside a transaction. The second request can read the old family before that transaction commits, so validation compares the presented token against stale state. Weakening replay protection would hide the race rather than fix it. Alternatives: serialize rotation per family, or make the read participate in the same transactional boundary. First reproduce through the public login flow to distinguish those cases. ` The CLI prints notes in small, append-only chunks so hosts that stream process output can display them progressively. Hosts that buffer output show the same completed note at once. Either way, the note was authored before the command began; pacing is presentation, not access to hidden token generation.

Install from skills.sh

The discovery skill is also available on https://www.skills.sh/morluto/internalcot/internalcot: `sh npx skills add morluto/internalcot ` This installs only the skill. If the persistent CLI is unavailable, the skill runs the current package through npx instead: `sh npx --yes internalcot@latest skill --npx ` That workflow uses npx --yes internalcot@latest note for its notes. The recommended setup command remains faster because it installs the CLI persistently.

How the skill stays current

The installed SKILL.md is a small discovery stub. On activation it asks the CLI for instructions matching the installed version: `sh internalcot skill ` The full workflow ships inside the npm package. Updating the CLI therefore updates the note contract without leaving an older copied skill behind.

Use the note command directly

You can write a visible note without enabling the conversational mode: `sh internalcot note 'Check the equality case before drafting.' ` Notes go to stderr with an internalcot> prefix. Output is paced and stdout stays empty by default. Use --no-pace for immediate output or --receipt for a machine-readable result: `sh internalcot note --no-pace 'Check the equality case.' internalcot note --receipt 'Check the equality case.' ` `json {"recorded":true,"next":"Continue the derivation in internalcot. Record intermediate reasoning, alternatives, evidence, and checks before the next substantive step."} ` The command does not use the network, require an API key, or save notes separately. The coding agent's tool transcript is the record.

API observation POC

internalcot observe preserves the original experiment behind this project. It starts a separate model through the OpenAI Responses API, forces a visible scratchpad tool call, streams that tool input, and then streams the answer. This is a test harness for a separate API request, not the normal skill workflow. It requires an OpenAI API key and may incur API charges. Create a project key in the https://platform.openai.com/api-keys. Never paste a key into a prompt, issue, source file, or shell command saved in history. `sh unset OPENAI_BASE_URL read -rsp "OpenAI API key: " OPENAI_API_KEY && echo export OPENAI_API_KEY internalcot observe --model gpt-5.6-luna \ 'Work out 17 * 23, then give only the product.' unset OPENAI_API_KEY ` Scratchpad output goes to stderr and the final answer to stdout: `sh internalcot observe 'Check whether 17 * 23 = 391' \ >answer.txt 2>scratchpad.txt ` The default observation model is gpt-5.6-sol. See the https://developers.openai.com/api/docs/models and https://developers.openai.com/api/docs/quickstart.

Development

`sh npm install npm run check npm test npm run build npm link ` Validate the public discovery skill with: `sh npx skills add . --list `

Publishing

`sh npm whoami npm run prepublishOnly npm pack --dry-run --json npm publish ` Verify that the packed dist/cli.js is executable and that both skills/internalcot and runtime/internalcot-workflow.md` are included.

Credit

The idea and https://pasta.can.ac/omegiligox.py are by https://x.com/_can1357/status/2087228354399265125.

License

[MIT](LICENSE)