internalcot

internalcot

internalcot gives coding agents a persistent, observable working-notes mode. An installed skill tells the current agent to call a small local CLI before substantive responses, so its model-authored scratchpad appears in the tool transcript.

This does not reveal private or provider-hidden chain-of-thought. It records notes that the model deliberately writes for observation.

Install the CLI and skill

Run the guided setup:

npx internalcot@latest setup

Setup always installs the persistent CLI and its skill together. Select Codex, Claude Code, or both; setup shows the exact global command and skill paths before it changes anything.

For a non-interactive Codex install:

npx internalcot@latest setup --codex --yes

Use --project to place the skill in the current repository instead of your home directory. Preview the complete installation without making changes:

# Preview without making changes
npx internalcot@latest setup --codex --project --dry-run

Setup writes only the bundled internalcot skill files. Re-running it reports an unchanged installation or updates those files while preserving unrelated files in the same directory.

The installed discovery skill is intentionally small. When $internalcot is invoked, it runs internalcot skill to load workflow instructions bundled with the installed CLI, so the instructions always match that CLI version.

Install the discovery skill only

The internalcot skill is also distributed through skills.sh. Install only the discovery skill with:

npx skills add morluto/internalcot

This does not install the CLI. If it is missing, the discovery skill uses npx --yes internalcot@latest for workflow and note calls, so skill-only installation still works. The recommended setup remains faster because it installs the CLI persistently. Restart your coding agent if the new skill does not appear immediately.

Turn working notes on

Explicitly invoke the skill without giving it a task:

$internalcot

The mode remains active for subsequent requests. The agent calls internalcot note before substantive work and again only when it has materially new reasoning state. The CLI output is the visible note, so the agent does not repeat it in prose.

Turn it off with:

$internalcot off

The toggle is conversational state carried by the skill instructions. It does not change the host's native reasoning setting or install a new first-class tool dynamically.

The installed skill loads the current workflow with:

internalcot skill

For a skill-only installation without a persistent CLI, the discovery skill loads an npx-ready workflow with:

npx --yes internalcot@latest skill --npx

Use the working-notes CLI directly

Pass a short note as one quoted argument:

internalcot note "Check the equality case before drafting."

The CLI displays the completed note in small, append-only chunks and writes nothing to stdout by default. This paced display works in hosts that stream process output and safely appears all at once in hosts that buffer it. It is presentation of an already-authored note, not token-by-token access to hidden reasoning.

For immediate output or a machine-readable receipt:

internalcot note --no-pace 'Check the equality case.'
internalcot note --receipt 'Check the equality case.'

The note is written to stderr with an internalcot> prefix. With --receipt, stdout receives:

{"recorded":true,"next":"Continue the work. Record another note only for materially new reasoning state."}

The command does not use the network, require an API key, or save notes to disk. The coding agent's tool transcript is the record.

Run the API observation POC

The separate observe command preserves the original experiment: it starts a second model through the OpenAI Responses API, sets its reasoning effort to none by default, forces an internalcot function call on the first turn, streams those tool arguments as a visible scratchpad, and then streams the final answer.

Create a project key in the OpenAI dashboard. Never paste a key into a prompt, issue, chat, source file, or shell command that will be saved in history. Revoke and replace any exposed key.

In Bash on macOS or Linux:

# Use OpenAI directly, not a previously configured compatible gateway.
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, so they can be captured separately:

internalcot observe "Check whether 17 * 23 = 391" \
  >answer.txt 2>scratchpad.txt

The default observation model is gpt-5.6-sol. See the OpenAI model catalog and API quickstart.

If you intentionally use an OpenAI-compatible gateway, set OPENAI_BASE_URL only for that gateway and use a credential issued by that provider.

Development

npm install
npm run check
npm test
npm run build
npm link

Validate the bundled skill with:

npx skills add . --list

Publishing

npm whoami
npm run prepublishOnly
npm pack --dry-run --json
npm publish

Verify the packed dist/cli.js is executable and the skills/internalcot and skill-data/internalcot directories are included before publishing.

Credit

The idea and original proof of concept are by Can Bölük (@_can1357).