Agents
insensical learns a coding agent's state in two ways, and lets the agent use insensical too.
- With no setup, from what agents already write to their terminal: their own reports (Claude Code makes them from version 2.1.295), progress, notifications and the bell, as in States and attention.
- Exactly, from the agent's own hooks, which call
isc status. insensical can add hooks for Claude Code, Codex, Gemini CLI, opencode, pi, Cursor CLI, Copilot CLI and Hermes.
The same setup lets an agent open, read and type into panes with isc. Ask it in your own words:
| You ask | The agent |
|---|---|
| "Open nvim with top in a narrow pane on the right." | Opens a tab with the editor, and top in a narrow pane beside it. |
| "Start the dev server in another tab and tell me when it's ready." | Starts it without taking your focus, and waits until it's listening. |
| "Run the tests beside you and fix what fails." | Runs them in a split, waits, and reads the failures. |
"Run \dt in the psql pane." | Types it into the pane named psql, presses Enter, and reads the answer. |
| "Show me that project, with bigger text." | Brings the project to the front and raises font-size. |
| "Close everything you opened." | Closes the panes it opened, and none of yours. |
Three things go in, per agent:
- Hooks that report its state.
- A skill the agent reads when a request is about terminals, panes or tabs. It tells the agent to run
isc guide, so a new version of insensical teaches every agent at once. - A note at the start of each session, inside a pane only, saying where the session runs and that
isc guideexplains insensical. An agent you started yourself is asked to name an unnamed tab after your task.
"Here", "beside you" or no place means the agent's own pane and tab. "The focused pane" means the one with the keyboard. A name always wins. An agent types only into panes it opened or that you named, and asks you first otherwise. It tells you about another agent's question and answers only when you ask.
isc guide prints the guide. isc guide layout, reading, acting, waiting and agents print one topic each. For an agent insensical doesn't set up, tell it to run isc guide.
Keeping agents out of a pane. For a pane with a production database, a secret or anything else no agent should see, choose Keep agents out of this pane in the palette (the protect command), or run isc protect PANE. To let them in, choose Let agents into this pane, or run isc protect PANE --off. It's kept with the layout, and the pane shows a crossed-out robot.
- A program in another pane can't read it (
isc capture,isc history,isc attach,isc status explain), wait on it (isc wait) or type into it (isc send,isc key,isc ask).iscexits with status 4, and the guide tells agents to tell you. isc lsin another pane still lists it, ending inkeeps agents out, with its title, tasks and running command left out.- You aren't refused anything: the window,
isc tuiandiscin a terminal outside insensical work as ever.iscrun in another pane is refused, whoever typed it, and so areisc --hostandisc tui --hostrun in a pane, on the other machine, once you've let agents on other machines in. A terminal you open from a pane is in that pane too. A window orisc hubyou start from a pane is you, as long as it's the one installed beside the server. Anything else in a pane is a program, whatever it says it is. - Only you let agents in again:
isc protect --offrun in a pane is refused. - It holds back an agent that follows what it's told. It isn't a wall: a program that runs as you can't always be told from you. One that leaves the pane, such as tmux or
setsidat a shell, counts as you, and so doesisc --hostrun in a pane withoutINSENSICAL_PANE. So does a browser connection carried byisc proxyrun in a pane, and a program that runs the window oriscits own way, or starts it in its own place after connecting.
WARNING
Letting an agent run isc lets it do anything you can. isc run, isc split and isc agent start open panes outside any sandbox the agent has, with your whole home and the network. Allow isc only in an agent you'd let run commands as you, and keep a pane that matters out of its reach.
Agents that start other agents. Claude Code, Codex and Gemini CLI can hand work to one another. Ask "have Codex review this diff" and the agent runs isc agent start codex "Review the diff". Codex opens in a new tab with the task as its first prompt, so you can watch it and take over. The starter waits with isc agent wait, which prints done and the whole reply, or waiting and the question. Both agents need their hooks set up.
| Command | Does |
|---|---|
isc agent start AGENT TASK | Opens the agent in a new tab, leaving your keyboard alone; --front brings it forward. --name NAME refuses while a pane of that name is there. |
isc agent wait | Waits for a turn to end. --timeout sets how long; it exits with status 124 when it runs out. |
isc agent tell PANE "MESSAGE" | Pastes a message as the agent's next prompt. While the agent works, it goes in when the turn ends. |
isc agent reply PANE | Prints the last whole reply again. |
isc agent answer PANE yes, no or words | Answers a permission prompt. Words refuse it and go in as the next prompt. |
--quiet on start | Runs the agent's one-question mode (claude -p, codex exec, gemini -p) with no pane and prints only its answer. |
isc ls --opened | Lists the agents started from this pane. |
isc close --opened | Ends the whole team, but for a pane you've typed into or focused. |
isc agent startwon't start an agent whose hooks aren't set up. It tells the asker to ask you to set it up. Agents never runisc integratethemselves.- If a started agent's hooks say nothing for a while, the pane turns to waiting for you with the likely reason: Codex runs no hook you haven't trusted with
/hooks, and Claude Code runs none in a folder you haven't trusted. answerpresses Enter or Esc for Claude Code,yor Esc for Codex, and1or Esc for Gemini CLI. Answer an agent whose prompt takes other keys in its pane.- A program can't answer, or type into, the agent in its own pane, nor in a pane it opened: its agent's questions are yours.
- A started agent can ask its starter something by ending its turn with the question. The starter's
isc agent waitreturns at once, and it answers withisc agent tell. tellandanswerneed the agent's own hooks, or the pluginisc integratewrites for opencode, pi and Hermes. pi and Hermes also pass on what they replied, soisc agent replyandwaitshow it; opencode doesn't.
One agent can have 8 agents open at once, and agents started by agents go 2 levels deep. Change them under Agents in the settings sheet, or with agents-at-once and agents-deep in config.toml.
Agents on other machines are kept out. An agent that runs isc --host or isc tui --host from a pane on another machine is refused here, and told how to let it in: turn on "Can agents on other machines use this computer?" under Agents in the settings sheet, or run isc config set agents-from-other-machines true. It takes effect at once. It's about agents only: you at a terminal of your own on another machine, the window, isc hub and agents on this computer aren't affected.
Setting up from the window
When an agent on the system isn't set up, the foot of the sidebar says so: "Codex can use insensical · Set up".
- Press it to list the agents, with each file that changes and what goes in it.
- Press Enter to add them. Nothing is ever added without that Enter.
- Press Escape to leave it for later.
- Press
N, or click the cross on the notice, to say never. - After adding, a line tells you what's still yours to do: for Codex, trusting the hooks with
/hooks(the dialog has an Open Codex to trust them button); for Hermes, enabling the plugin. - "Set up the agents on this system to use insensical" in the palette asks at any time, and includes the agents you declined.
In isc tui, Ctrl+Space then Shift+A asks, Enter sets up, Esc leaves the notice and N says never. Declined agents are kept in ~/.local/state/insensical/agents-declined, one per line. Delete a line to be offered that agent again.
Setting up from the command line
| Command | Does |
|---|---|
isc integrate | Finds the agents on this system, shows what would change for each, and asks. |
isc integrate claude | The same for one agent: claude, codex, gemini, opencode, pi, cursor, copilot or hermes. |
isc integrate --yes | Adds every agent found, without asking. |
isc integrate --remove | Removes them all, or the one you name. |
isc integrate --force | Replaces a skill called insensical that insensical didn't write. With --remove, removes it. |
isc integrate --status | Prints what was found and how each agent's hooks, skill and note stand, as JSON. Changes nothing. |
- An agent counts as found when its program is on
PATHor its settings directory exists. - With no terminal to ask on,
isc integratechanges nothing unless you pass--yes, and exits with status 1. - With
--host, it's the other machine's agents, and you must give--yesor--remove --yes. Its daemon must be running. --statuscan't be combined with--remove,--yesor--force. For each agent it printsagent,title,found,integrated,stale,file,itemsandthen.itemshashooks,skillandnote, each with afileand astate:current,outdated,missing,foreignorunsupported.- A hook of your own that isn't
isc hook AGENTis never changed or removed. An agent's settings file over 16 MB, or one that can't be read as text, is left as it is. CLAUDE_CONFIG_DIRand the other agents' variables count only when they hold a whole path, from/.
WARNING
The hooks name isc by the full path it had when you ran integrate. If you move or reinstall isc, the agent's state stops being reported and the window offers to set it up again. Run isc integrate for that agent to rewrite them.
What each agent gets:
| Agent | Hooks or plugin | Skill | Note at a session's start | Resume offered |
|---|---|---|---|---|
| Claude Code | ~/.claude/settings.json, or under $CLAUDE_CONFIG_DIR | ~/.claude/skills/insensical/SKILL.md | A hook | claude --resume <session> |
| Codex | ~/.codex/hooks.json, or under $CODEX_HOME | ~/.agents/skills/insensical/SKILL.md | A hook | codex resume <session> |
| Gemini CLI | ~/.gemini/settings.json, or $GEMINI_CLI_HOME/.gemini/settings.json | ~/.agents/skills/insensical/SKILL.md | A hook | None |
| opencode | ~/.config/opencode/plugins/insensical.js (under $XDG_CONFIG_HOME) | ~/.agents/skills/insensical/SKILL.md | None | opencode --session <id> |
| pi | ~/.pi/agent/extensions/insensical.ts, or under $PI_CODING_AGENT_DIR | ~/.agents/skills/insensical/SKILL.md | None | pi --session |
| Cursor CLI | ~/.cursor/hooks.json | None | A hook in hooks.json | None |
| Copilot CLI | ~/.copilot/hooks/insensical.json, or under $COPILOT_HOME | ~/.agents/skills/insensical/SKILL.md | A hook | copilot --resume <session> |
| Hermes | Plugin in ~/.hermes/plugins/insensical, or under $HERMES_HOME | ~/.hermes/skills/insensical/SKILL.md, or under $HERMES_HOME | The plugin, at the first turn | hermes --resume <session> |
- Hook files you already have are kept, with a copy saved once beside them as
*.before-insensical.--removetakes only insensical's hooks out. Files insensical writes whole (opencode, pi, Copilot CLI, Hermes) are deleted. - A skill called
insensicalthat insensical didn't write is yours:--forcereplaces it. Five agents share the one skill in~/.agents/skills, and removing one leaves it while another is set up. - Hooks print nothing, never fail and do nothing outside a pane.
What each agent reports:
| Agent | running | waiting | done | failed | idle |
|---|---|---|---|---|---|
| Claude Code | A prompt; a tool has run | A permission or a question | It finished responding, with its first line; not while work it started in the background is still going | It stopped on an error | A session starts or ends |
| Codex | A prompt; a finished tool | A request for approval | End of a turn, with its first line | Not reported | An interrupted turn |
| Gemini CLI | A prompt; a finished tool | Asking to use a tool | End of a turn, with its first line | Not reported | None |
| opencode | Working | A permission or a question | Going quiet after working | An error, with its message | A turn you stopped |
| pi | Working | A dialog an extension puts up | Finishing, with what it said | Ending in an error | Stopping it yourself |
| Cursor CLI | A prompt; a finished tool | Never | End of a turn | A turn that errors | A turn you stopped |
| Copilot CLI | A prompt; a tool | A request for permission | End of a turn | An error it can't get past | None |
| Hermes | Working | A command or a question | Finishing, with its first line | Same as idle | A stopped turn, or none ended without an answer |
Claude Code
Claude Code 2.1.295 and later also reports in its own terminal (States and attention), and that's what the pane shows. Keep the hooks: they name the session to resume (Stopping, restarting and new versions).
When Claude runs several tools at once and one finishes while another still waits for your answer, the row keeps saying waiting until that tool has run, a new tool starts, the turn ends or you send a prompt. Codex, Gemini CLI and Copilot CLI work the same way.
Codex
Codex does not run a hook until you trust it. After integrating, open Codex, run /hooks, and trust the new ones. Until you do, nothing is reported. If isc moves and you add the hooks again, trust them again.
Gemini CLI
A failed or cancelled turn isn't reported, so the pane stays running until the next prompt.
opencode
Sessions that opencode starts itself (subagents) aren't reported.
pi
pi reports only when it's running with a screen. It never asks before using a tool, so waiting comes only from a dialog an extension shows.
Cursor CLI
It never says waiting. Cursor has no event for a question it asks you, so the pane stays running until you answer. What it said at the end of a turn isn't shown.
Copilot CLI
What it said at the end of a turn isn't shown. Your own hook files in ~/.copilot/hooks aren't touched.
Hermes
Hermes doesn't load a plugin until you enable it. After integrating, run hermes plugins enable insensical. Until you do, nothing is reported. Agents that Hermes starts itself (subagents) aren't reported.
Any other agent or script
Any agent or script can call isc status and isc notify from its own hooks.
isc status running
isc status waiting -m "Allow \`cargo publish\`?"
isc status done
isc status running --resume "mytool --continue 42"
isc notify "Build" "Finished"--resumesays how to pick the work up again. The pane offers that command at its prompt after the daemon has stopped, once, and not if the program ended by itself.- Inside a pane they need nothing more. Outside one they need
--pane. - A message that begins with a hyphen works:
isc status done -m "- fixed". In a script,--message="$text"keeps the text and the option together.
Agents that open their helpers in tmux panes
Some agents start helpers, each in a pane of its own, by running tmux commands, but only inside tmux. With the tmux-shim setting on, those helpers open as panes here, beside the agent, and you can move, name and zoom them like any pane.
isc config set tmux-shim trueOr switch on "Answer as tmux" in the settings sheet, under Terminal. It's off until you turn it on, and applies to panes started afterwards.
NOTE
While it's on, tmux in a pane is isc, not the real tmux. If you use tmux yourself inside insensical, run it by its full path, such as /usr/bin/tmux, or leave the setting off. Nothing outside insensical's panes changes.
A session is a project, a window is a tab, and a pane is a pane. Targets are written as in tmux: %5, @7, $3, api:0.1, api:logs, :1.
- Understood:
split-window,new-window,new-session,respawn-pane -k,send-keys,kill-pane,kill-window,select-pane,select-window,rename-window,list-panes,list-windows,list-sessions,display-message -p,capture-pane -p,resize-pane,select-layout,has-sessionand-V. Common flags work (-h,-b,-l,-p,-c,-e,-d,-P -F,-n,-s,-S,-E,-Z). Chain commands with;. - Formats:
pane_id,pane_index,pane_title,pane_current_command,pane_current_path,pane_start_command,pane_active,pane_width,pane_height,pane_dead,pane_dead_status,window_id,window_index,window_name,window_active,window_panes,window_zoomed_flag,session_name,session_id,session_windows,session_attached,client_control_mode,version,#S,#I,#W,#P,#D,#Tand#{?name,this,that}. - Accepted and ignored:
set-option,set,set-window-option,bind-key,unbind-key,source-file,set-hook,set-environment,start-serverandrefresh-client. - Refused:
kill-server. Onlyisc kill-serverstops every pane. - Anything else is
unknown command, with exit status 1.
Limits:
- A pane closes when its program ends:
remain-on-exitisn't kept. respawn-paneneeds-kand a command.capture-paneneeds-p. A session can't be attached to.main-verticalandmain-horizontalgive the main pane half the tab.- Opening a pane in a tab you aren't looking at shows you that tab briefly;
-dreturns the keyboard. - If your shell's start-up file replaces
PATHinstead of adding to it, a program you start won't findtmux.