clinky — thinking made visible

A visual and sonic surface for AI thinking. Works with claude, copilot, and codex. The name: cli + thinking = clinky.

Not a chat interface. Not a document. A living map of how a thought unfolds — branches, choices, narrowings, dead ends, resolutions — rendered as something you'd want to look at and listen to.

Demo

Live replays at clinky-demo.ichbinsoftware.com — install locally to run your own prompts.

Install

npm install -g @ichbinsoftware/clinky

Then run:

clinky               # default: claude backend, port 4243
clinky --open        # also opens the browser for you

Open http://localhost:4243 in your browser (substitute your --port if you changed it). Pick a mode, type a question, press think.

Flags

clinky --open                        # also opens the browser for you
clinky --agent copilot               # use GitHub Copilot CLI
clinky --agent codex                 # use OpenAI Codex CLI
clinky --model claude-opus-4-7       # override the default model for the chosen agent
clinky --port 4244                   # change port
clinky --record                      # save every session to ~/.clinky/sessions/
clinky --verbose                     # log every node arrival to stderr

Recorded sessions are listed at /api/sessions. Replay any via /api/replay/<id> — append ?speed= (default 4×, 0 = instant) to control playback rate.

?agent= and ?model= on any URL override the defaults for that request — use them from /inspect to make a new request with a different backend or model without restarting.

Requirements

• Node 18+
• At least one agent backend installed and authenticated:
  • claude (default) — npm i -g @anthropic-ai/claude-code
  • copilot — npm install -g @github/copilot
  • codex — npm i -g @openai/codex

A note on capabilities

The CLI agents are general-purpose AI tools with file access, Bash, and OS-level integrations. clinky's system prompt constrains them to emit thought nodes, but a prompt like "write a CLI that gets weather based on location" may still cause the agent to reach for GPS, calendar, or filesystem. On macOS this triggers permission dialogs — you can deny them; clinky itself only needs network access. Keep prompts conceptual ("how would I design a weather CLI?") to stay in pure thinking mode.

Running from source

git clone https://github.com/ichbinsoftware/clinky
cd clinky
node server.js

Open http://localhost:4243 in your browser (substitute your --port if you changed it). Same flags as the published CLI.

How it works

1. User types a prompt and presses think
2. Server spawns the selected agent with a system prompt instructing it to emit thought nodes via Bash tool calls (one echo '{...}' per thought)
3. Each Bash invocation arrives in real time — no waiting for the full response
4. Server extracts JSON from the Bash output, classifies topics, assigns colors + notes
5. Nodes stream to the browser via SSE
6. Each mode renders the node as a visual element with a synthesized sound

The Bash commands are never executed. The call is a delivery mechanism — the server parses JSON out of the command string and discards it. Bash is used because it's universal across all three backends and provides a real-time tool_use event the instant the model invokes it, before output is ready. The model is asked to batch 3–4 thoughts per call for speed.

The thought node

{
  "id": 12,
  "topic": "channels",
  "type": "choice",
  "text": "for most launches: one owned + one paid",
  "confidence": 0.75,
  "stance": "claiming",
  "refs": [9, 10, 11],
  "rel": "synthesizes",
  "because": [9, 10, 11],
  "heat": 0.4
}

• types: claim, branch, choice, dead-end, aside, resolution
• stance: exploring | claiming | questioning | conceding
• rel: supports | contradicts | synthesizes | refines | questions | supersedes (required when refs is set)
• because: array of prior ids, or "external" / "prior" (required on claim, choice, resolution)
• heat: 0–1 — reserved for unexpected or consequential moves

Each response carries 4–8 topics, each assigned a stable color and a pentatonic note for the session.

Server-stamped on every node: batch_id, batch_position, elapsed_ms, incoming_refs_count (how many later thoughts reference this one — delivered via a separate graph SSE event).

The relational fields turn the stream into a reasoning trace rather than a list. Open /inspect during any session for live coverage of the fields.

The reflection

At the end of every session the model emits one final type: "reflection" node — a single sentence of meta-commentary on its own thinking. It surfaces in the reading-pane essay panel as a closing block, not on the canvas.

The 31 modes

Field & Canvas — painting, mark-making, gesture

Sky & Cosmos — expansive, mythic, open

Physics & Emergence — forces, motion, simulation

Grid & Geometry — built forms, sequences, regular grids

Data & Structure — analytical diagrams, signal forms

Frame & Chart — strategy-deck and workshop-wall diagrams

Sound

A Web Audio synthesis engine — no samples, no files. Each session plays as a piece of music whose structure mirrors the thinking.

Aesthetic (picked per mode): one of ambient, classical, jazz, industrial, techno, videogame. Each carries its own waveforms, envelopes, voicings, FX (reverb / delay / distortion), and key palette. Ambient is wide pads with long reverb; videogame is square-wave chiptune; industrial is sawtooth + crunch; classical is detuned triangle in a hall.

Session key is hashed from the prompt — the same prompt always plays in the same key. Each topic gets a stable note within that key, so the same topic always sounds the same across the session.

Stance shapes the articulation of every thought:

Rel between thoughts plays as a two-note interval:

Heat (unexpected / consequential flag) boosts velocity and reverb send. Because grounds the thought from below: internal lays a pedal tone, external plays off-stage with extra reverb and pan, prior detunes flat to suggest a memory. Some aesthetics also run a rhythmic bed underneath the harmony.

Controls

Pressing think clears the canvas first, then streams the new session. Use clear to wipe back to an empty canvas without starting one.

Hover any element to see the thought behind it. Click to isolate a topic; click again to release. The hub/centre/spine of any radial mode is a reset handle.

Architecture

browser (31 mode pages + /inspect)
  ↑ SSE: status, topics, batch, node, graph, usage, done, error
  ↑ Web Audio: per-thought synthesized tones
  │
server.js
  ├─ GET /                → mode picker
  ├─ GET /<mode>          → mode page
  ├─ GET /inspect         → diagnostic stream viewer
  ├─ GET /api/think?prompt=&mode=&model=&effort=&agent=  → SSE stream
  ├─ GET /api/sessions    → list recorded sessions
  └─ GET /api/replay/<id>?speed=&mode=  → replay a recorded session

agents/ (one file per backend)
  ├─ shared.js     ← SYSTEM_PROMPT, extractAndEmitNodes, runWithProvider
  ├─ claude.js     ← spawns claude --output-format stream-json
  ├─ copilot.js    ← spawns copilot --output-format json
  └─ codex.js      ← spawns codex exec --json

Every mode is a class extending Mode (/public/mode.js). The base class owns canvas setup, resize, chrome, SSE lifecycle, RAF loop. Each mode implements draw() and overrides hooks (onNode, onClear, onDone).

Backend comparison

Any model name passes through — no allowlist, new models work automatically. Effort: low | medium | high (default) | xhigh | max.

No server dependencies

Server uses Node built-ins only (http, fs, path, url, child_process). Client is vanilla JS + Canvas API + Web Audio API. No npm packages, no bundler, no build step.

Influences

• Electroplankton (Toshio Iwai, Nintendo DS) — playful, no goal, sound and visual inseparable
• Brian Eno — generative systems that produce music reflecting real structure
• Edward Tufte — information density without clutter
• Conway's Game of Life — emergent complexity from simple rules
• Mark Rothko — color as weight, presence without form

License

MIT