Skip to content

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 askThe 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 guide explains 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). isc exits with status 4, and the guide tells agents to tell you.
  • isc ls in another pane still lists it, ending in keeps agents out, with its title, tasks and running command left out.
  • You aren't refused anything: the window, isc tui and isc in a terminal outside insensical work as ever. isc run in another pane is refused, whoever typed it, and so are isc --host and isc tui --host run 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 or isc hub you 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 --off run 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 setsid at a shell, counts as you, and so does isc --host run in a pane without INSENSICAL_PANE. So does a browser connection carried by isc proxy run in a pane, and a program that runs the window or isc its 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.

CommandDoes
isc agent start AGENT TASKOpens 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 waitWaits 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 PANEPrints the last whole reply again.
isc agent answer PANE yes, no or wordsAnswers a permission prompt. Words refuse it and go in as the next prompt.
--quiet on startRuns the agent's one-question mode (claude -p, codex exec, gemini -p) with no pane and prints only its answer.
isc ls --openedLists the agents started from this pane.
isc close --openedEnds the whole team, but for a pane you've typed into or focused.
  • isc agent start won't start an agent whose hooks aren't set up. It tells the asker to ask you to set it up. Agents never run isc integrate themselves.
  • 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.
  • answer presses Enter or Esc for Claude Code, y or Esc for Codex, and 1 or 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 wait returns at once, and it answers with isc agent tell.
  • tell and answer need the agent's own hooks, or the plugin isc integrate writes for opencode, pi and Hermes. pi and Hermes also pass on what they replied, so isc agent reply and wait show 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 ​

CommandDoes
isc integrateFinds the agents on this system, shows what would change for each, and asks.
isc integrate claudeThe same for one agent: claude, codex, gemini, opencode, pi, cursor, copilot or hermes.
isc integrate --yesAdds every agent found, without asking.
isc integrate --removeRemoves them all, or the one you name.
isc integrate --forceReplaces a skill called insensical that insensical didn't write. With --remove, removes it.
isc integrate --statusPrints 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 PATH or its settings directory exists.
  • With no terminal to ask on, isc integrate changes nothing unless you pass --yes, and exits with status 1.
  • With --host, it's the other machine's agents, and you must give --yes or --remove --yes. Its daemon must be running.
  • --status can't be combined with --remove, --yes or --force. For each agent it prints agent, title, found, integrated, stale, file, items and then. items has hooks, skill and note, each with a file and a state: current, outdated, missing, foreign or unsupported.
  • A hook of your own that isn't isc hook AGENT is 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_DIR and 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:

AgentHooks or pluginSkillNote at a session's startResume offered
Claude Code~/.claude/settings.json, or under $CLAUDE_CONFIG_DIR~/.claude/skills/insensical/SKILL.mdA hookclaude --resume <session>
Codex~/.codex/hooks.json, or under $CODEX_HOME~/.agents/skills/insensical/SKILL.mdA hookcodex resume <session>
Gemini CLI~/.gemini/settings.json, or $GEMINI_CLI_HOME/.gemini/settings.json~/.agents/skills/insensical/SKILL.mdA hookNone
opencode~/.config/opencode/plugins/insensical.js (under $XDG_CONFIG_HOME)~/.agents/skills/insensical/SKILL.mdNoneopencode --session <id>
pi~/.pi/agent/extensions/insensical.ts, or under $PI_CODING_AGENT_DIR~/.agents/skills/insensical/SKILL.mdNonepi --session
Cursor CLI~/.cursor/hooks.jsonNoneA hook in hooks.jsonNone
Copilot CLI~/.copilot/hooks/insensical.json, or under $COPILOT_HOME~/.agents/skills/insensical/SKILL.mdA hookcopilot --resume <session>
HermesPlugin in ~/.hermes/plugins/insensical, or under $HERMES_HOME~/.hermes/skills/insensical/SKILL.md, or under $HERMES_HOMEThe plugin, at the first turnhermes --resume <session>
  • Hook files you already have are kept, with a copy saved once beside them as *.before-insensical. --remove takes only insensical's hooks out. Files insensical writes whole (opencode, pi, Copilot CLI, Hermes) are deleted.
  • A skill called insensical that insensical didn't write is yours: --force replaces 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:

Agentrunningwaitingdonefailedidle
Claude CodeA prompt; a tool has runA permission or a questionIt finished responding, with its first line; not while work it started in the background is still goingIt stopped on an errorA session starts or ends
CodexA prompt; a finished toolA request for approvalEnd of a turn, with its first lineNot reportedAn interrupted turn
Gemini CLIA prompt; a finished toolAsking to use a toolEnd of a turn, with its first lineNot reportedNone
opencodeWorkingA permission or a questionGoing quiet after workingAn error, with its messageA turn you stopped
piWorkingA dialog an extension puts upFinishing, with what it saidEnding in an errorStopping it yourself
Cursor CLIA prompt; a finished toolNeverEnd of a turnA turn that errorsA turn you stopped
Copilot CLIA prompt; a toolA request for permissionEnd of a turnAn error it can't get pastNone
HermesWorkingA command or a questionFinishing, with its first lineSame as idleA 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.

sh
isc status running
isc status waiting -m "Allow \`cargo publish\`?"
isc status done
isc status running --resume "mytool --continue 42"
isc notify "Build" "Finished"
  • --resume says 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.

sh
isc config set tmux-shim true

Or 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-session and -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, #T and #{?name,this,that}.
  • Accepted and ignored: set-option, set, set-window-option, bind-key, unbind-key, source-file, set-hook, set-environment, start-server and refresh-client.
  • Refused: kill-server. Only isc kill-server stops every pane.
  • Anything else is unknown command, with exit status 1.

Limits:

  • A pane closes when its program ends: remain-on-exit isn't kept.
  • respawn-pane needs -k and a command. capture-pane needs -p. A session can't be attached to.
  • main-vertical and main-horizontal give the main pane half the tab.
  • Opening a pane in a tab you aren't looking at shows you that tab briefly; -d returns the keyboard.
  • If your shell's start-up file replaces PATH instead of adding to it, a program you start won't find tmux.