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

Choose CLI + skill, then 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. Other useful variants are:

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

# The persistent command already exists
npx internalcot@latest setup --codex --skill-only --yes

# Install only the command
npx internalcot@latest setup --cli-only --yes

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.

You can also install each part manually:

npm install --global internalcot
npx skills add morluto/internalcot

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.

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.

Use the working-notes CLI directly

Pass a short note as arguments:

internalcot note "Check the equality case before drafting."

For multiline notes, use stdin:

internalcot note <<'INTERNALCOT'
Goal: prove descent from the equation.
Constraint: handle every equality case.
Check: verify the mutated coordinate stays positive.
INTERNALCOT

The note is written to stderr with an internalcot> prefix. Stdout receives a small JSON receipt:

{"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 directory is included before publishing.

Credit

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