The Ishoo manual

Getting started

Getting started with Ishoo takes five steps: check you have what it needs, install it, add your project, connect your coding agent, and ask the agent to make a first small plan. Each step has its own page in this chapter.

1. Check what you need

   A supported computer, a coding agent that can use MCP tools, and a project folder.

2. Install Ishoo

   One installer sets up everything.

3. Add your project

   Point Ishoo at the folder.

4. Connect your agent

   Ask it to check that it can see the Ishoo tools.

5. Make your first plan

   Describe what you want; the agent writes a small plan for you to read.

Before you start

Ishoo needs a Windows x64 or Debian/Ubuntu x64 computer, a coding agent that supports MCP tools (Claude Code or Codex) installed and working, and a project folder. Ishoo uses Git underneath, and the installer checks for it.

• Not complete: A Windows x64 or Debian/Ubuntu x64 computer. There is no macOS build yet.
• Not complete: Claude Code or Codex installed and working. A regular chat in a web browser is not the same thing: the agent has to be able to work with files on your computer.
• Not complete: A project folder: an existing project, or an empty folder for a new idea.
• Not complete: Your own AI plan or API access. Ishoo doesn’t include one.

Install Ishoo

Ishoo installs from one download: a Windows installer or a Debian/Ubuntu package. The installer puts ishoo on your PATH, starts its background service and connects Claude Code and Codex. Ishoo is not available to download yet; installers open at launch.

1. Download the installer for your computer

   A .exe for Windows or a .deb for Debian and Ubuntu. One file installs everything.

2. Run it

   The installer places the ishoo program, puts it on your PATH, installs the small background service your agent talks to, and checks that it answers.

3. Open Ishoo

   From the Start menu or your app grid. On first launch Ishoo checks this machine’s setup, finishes anything missing, and tells you in one sentence what it did.

4. Restart your agent

   If Claude Code or Codex was already open, restart it so it picks up the new tools.

Ishoo never removes or switches off anything you already rely on. If your agent already has other tools set up, they stay as they were; Ishoo only adds its own entry.

Add your project

You add a project in Ishoo by clicking the project name next to the wordmark, choosing All projects, then Add project and picking the folder. Ishoo opens an existing Ishoo project directly or walks you through setting up a new one.

1. Open the project switcher

   Click the project name beside the Ishoo. wordmark at the top of the rail, then All projects….

2. Add project

   Pick the folder. If it already has Ishoo records, it opens straight away. If not, Ishoo shows a short setup screen.

3. Work in the same folder

   Start your coding agent in that same folder. Ishoo and the agent have to be looking at the same project.

Your agent reaches Ishoo through a small background service Ishoo keeps running on this computer. Setup registers that service with Claude Code and Codex for you, so you don’t need to edit any config files.

Connect your agent

You check the connection by asking your agent, in the project folder, whether it can access the Ishoo tools. A connected agent sees tools named ishoo_status, ishoo_plan and so on. The rail footer in the app also says whether agents are configured.

Ask your agent:

A connected agent calls ishoo_status and reports the project, its active plan and a suggested next step. When it connects, it also receives Ishoo’s working rules automatically and can re-read them with ishoo_brief.

Make your first plan

You start by asking your connected agent to use Ishoo to make a small plan, then explaining your idea in your own words. The agent files the plan and its tasks in Ishoo; you read them under Your plan and ask for changes before it starts.

Tell your agent:

Then describe the idea however it comes out. Ask for the smallest version you could actually try: one page, one feature, one screen.

1. Read the plan

   Open Your plan. Each plan has an outcome and an ordered list of tasks.

2. Open a task

   Every task carries a scope: the concrete change, where it happens, the proof that it’s done, and what’s out of scope. If a task is vague, too big, or unnecessary, say so.

3. Say go

   When the plan looks right, tell the agent to start. The eye switches to Working.

Coming back later

You pick up by opening Ishoo to read Home and the rail, then starting a new conversation in the same folder and asking the agent to read the Ishoo plan and decisions and tell you where things stand before it changes anything.

The record lives in the project, not in one conversation’s memory, so it works just as well tomorrow, next month, or with a different agent.

A second computer

To use an Ishoo project on a second computer, install Ishoo there, clone the project, and run ishoo enable in the clone. Enable brings in the project’s records from the remote and sets up this computer’s agent connection. ishoo status then shows the same tasks and plans.

1. Install Ishoo

   Use the installer on the second computer, the same as the first.

2. Clone the project

   git clone <your remote>, as you normally would. A plain clone does not bring Ishoo’s records yet; that is fine.

3. Run ishoo enable in the clone

   It fetches the records from the remote (they travel on refs/ishoo/store), writes this computer’s agent settings and hooks, and keeps the project’s saved choice about CLAUDE.md.

4. Check it

   Run ishoo status in the clone: it shows the same active plan and tasks as the first computer. Then add the folder in the app with Add project, and start your agent in that folder.

The window

The Ishoo window has a dark rail on the left and three tabs on the right. The rail holds the eye, the task in focus, and Plan and People tabs. The tabs are Home (the timeline), Your plan and Decisions. A backup chip sits at the top right.

Click the project name beside the Ishoo. wordmark to switch projects. The Settings button in the top bar opens Settings. The rail footer says whether your agents are configured, and shows the result of the last project update.

Clicking any task, anywhere, opens it in the same place: a panel that fills the right-hand side. Back or Esc closes it.

The eye

The Ishoo eye shows one of four looks. Ready: nothing needs you and the next task is waiting. Working: your agent is on a task and you can look away. Needs you: work stopped and needs a person. No plan yet: nothing is planned.

Under the state word is how long it has been true, for example “for 12m”, or what last happened, such as “UI-25 landed · 53m ago”.

The rule behind the eye: a big button only appears when you’re needed. A calm rail has nothing to press.

The plan tape

The plan tape is the grid of keys under the rail’s Plan tab, one key per task in the shown plan, in order. A tick means done, a play mark means active, a lock means blocked, a dash means retired, and a blank key is still to go. Click a key to open its task.

Pointing at a key names it on the line underneath, with its number and title. With nothing under the pointer, that line names the active task, or the first unfinished one. An owned task shows its owner’s initials when you point at it.

Under the tape a count row totals done, active, blocked and to go, and the header shows done out of total.

The plan name above the tape is a menu (Show plan). Picking another plan only previews it; each one is marked active plan, complete or preview. To make the shown plan the one your agent works on next, press Set active.

Home: the timeline

The Ishoo Home timeline is the project’s full recorded history, newest first and grouped by day: tasks filed, started, split and landed, plans made, decisions recorded and releases. It can be filtered by kind and searched by id or title.

The chips above the list filter to one kind (All, Started, Landed, Releases, Splits, Filed, Plans, Decisions). The search box matches a task id or title. Days are headed Today, Yesterday, then weekday and date.

The line beside the chips counts exactly what is shown: how many events, and how many of them landed. The timeline shows 60 rows at a time; Show more loads the next page, so a project with thousands of events stays fast.

Switching projects

You switch projects in Ishoo by clicking the project name beside the wordmark, choosing All projects, and clicking the project you want. Your projects lists every project on this computer. Forget removes one from the list without touching its files.

Ishoo is one app for all your projects. Your projects lists every folder you’ve added; click one to open it. Add project picks a new folder. Pointing at a project shows Forget, which removes it from the list. The project’s files and records are not deleted.

When no project is open, Ishoo opens straight to Your projects. Back returns to the project you had open.

Settings

Ishoo’s Settings shows your license, who you are on this computer, whether your records are being published and ownership changes can be confirmed, the Require code review switch, and the four export options.

Plans

Ishoo plans are named lists of tasks with a stated outcome, such as Finish the beginner launch. Every task belongs to exactly one plan. One plan is active: it is what your agent works on next. Your plan lists every plan with its progress.

A plan is a group of tasks that together reach one outcome. Every plan states that outcome as one sentence: “when this plan is done, ___ is true.” Every task in it states, in one line, why it’s needed for that outcome. A task that can’t say why belongs in a different plan.

Plans are the only way to group work in Ishoo. There are no epics, milestones or boards to keep in step.

Ask your agent to make, rename, reorder or archive plans. Backlog is the plan tasks fall back to when nothing better fits, but a new task always has to name a plan when it’s filed.

Plan order

Ishoo orders a plan from its blockers: when one task has to wait for another, that link is recorded, and the plan runs in an order that respects it. A task can’t start while something it waits on is unfinished. Otherwise the order is a suggestion.

Every task says what it waits on (or explicitly that it waits on nothing). Ishoo turns those links into the plan’s order, so the order can’t drift away from reality the way a hand-sorted list does.

A blocked task shows a lock on the plan tape and counts as blocked. When the task it waits on lands, it unlocks by itself.

Priority levels

Ishoo has five priority levels. Urgent: the cost grows while it waits, so it goes first across all plans. Important: high value, but waiting costs nothing extra. Mid: normal work. Later: deferred. Shelved: kept as knowledge, out of the queue.

A task can also have no level, which sits between Mid and Later. Each task has at most one level.

Tasks

An Ishoo task holds a scope written before work starts (concrete change, main surface, proof of done, out of scope), results written after it ends, plus its status, owner, priority, labels, linked decisions, blockers, files and a comment thread.

Each task has an id made of a short category and a number, like UI-12 or FIX-03, and one of four statuses: Backlog (not started), Active (being worked on), Done (landed), or Retired (declined or replaced).

Your agent writes tasks. You can change one yourself with Edit: title, category, status, priority, owner, labels, governing decisions and the four scope fields. The form won’t save without a title, a category, all four scope fields and at least one governing decision. Delete is in the same form.

Scope: before work starts

An Ishoo task must state four things before work starts: the concrete change, the main surface where it happens, the proof that it’s done, and what’s out of scope. It must also name its plan, why it fits that plan, its governing decisions and its blockers.

Read Proof of done before your agent starts. It’s the promise you’ll hold the finished work to.

Results: after work ends

An Ishoo task records four things when work finishes: what changed, why, how it was verified, and a handoff note for whoever comes next. A task cannot land until all four are written, and they must answer the scope written at the start.

When a task lands, these four fields also become the description of the change in your project’s history, so the record and the code say the same thing.

Comments

Every Ishoo task has a comment thread. Open a task and press Add a comment or Open thread. You and your agent can add, edit and delete comments; each shows its author’s initials and the date.

The task panel shows how many comments there are and the latest one. The thread opens in place of the task; Back returns to it. Hover a comment to Edit or Delete it.

Comments are a good place for things that aren’t part of the scope: a question for the agent, a note for later, a link to where something was discussed.

Splitting big tasks

Ishoo splits a big task into smaller child tasks and keeps the link between them. The parent shows its children under Lineage, each child shows which task it was split from, and the timeline records one Split event with the children as chips.

A task gets split when it’s too big to land in one go, often because the change-size limit blocked it. Each child is a full task with its own scope, and the parent stays open as an umbrella.

When every child is done, the parent shows Ready to resolve: its results can be written and it can be closed.

Retiring ideas

Ishoo retires a task it won’t do instead of deleting it. Declined keeps the idea with the reason it was rejected; superseded points to the task that replaced it; shelved keeps it as knowledge out of the queue. All stay searchable.

Retired tasks show as a dash on the plan tape and as Retired in filters. They leave the queue but not the record, so nobody proposes the same rejected idea again without seeing why it was dropped.

People

Ishoo keeps a list of the people who work on a project, each with a name, title, short bio and photo. The rail’s People tab shows everyone; Manage registers you or edits your own entry. Each computer remembers which person you are.

Open the rail’s People tab to see People on this project. Manage opens your own entry: Register yourself the first time, then Save to change your name, title, short id, bio or photo. You can only edit yourself; other people manage their own entries.

Which person you are is remembered per computer and isn’t shared. On a new machine, choose yourself with Use on this machine. If you start work before choosing, Ishoo asks Who are you?.

Ownership and handoff

Each Ishoo task being worked on has one owner, recorded on the task, which lasts across restarts until the owner stops, hands it off, or finishes it. The task panel shows the owner with Start, Stop, Hand off and Take over.

Owners’ initials show on the plan tape when you point at an owned task, so you can see who’s on what.

How work lands

Ishoo marks a task done only when it lands: the agent freezes one exact version of the change, the task’s checks are recorded against that exact version, and it is integrated into your main branch. Until then the task stays open where you can see it.

1. Start

   The agent takes ownership of the task. Ishoo gives it a private workspace, so unfinished work never touches your main branch.

2. Work

   The agent changes code in its workspace. The eye says Working.

3. Write the results

   What changed, why, how it was checked, and the handoff.

4. Verify

   Checks run against the exact candidate. Required checks must pass, advisory ones are reported, and invariant checks can never be waived.

5. Submit or land

   Direct landing is the default. In pull-request mode, Ishoo submits the verified candidate and the task stays active, awaiting review. Only a confirmed merge into the integration branch makes it done and releases its workspace.

In pull-request mode, done returns SUBMITTED. If GitHub CLI is signed in, Ishoo opens the PR. Otherwise use the supplied compare link, title and body and click GitHub Create pull request. Home and task detail show the PR link and recorded submission state. Poll status for merge, closure or changes requested; make requested changes in the retained workspace, verify a fresh candidate and submit again.

A confirmed merge records exact_tree=true when the landed tree matches the verified candidate. exact_tree=false means the task landed with a different tree; candidate checks do not certify that tree. Closed without merge and changes requested remain active and need attention. Ishoo never force-pushes or bypasses branch protection.

Private workspaces and Git

Ishoo gives each task its own Git worktree and branch, so unfinished work never touches main. Landing turns the finished work into one commit described from the task’s results and pushes it, or submits it as a pull request and waits for a proven merge. Stopping a task saves its unfinished work first.

In plain terms: every task gets its own separate copy of your project to work in. Your main code only changes when a task lands, and then all at once, as one clean change you can read.

Work outside the project

A task whose real change is outside the project folder, such as a desktop launcher or a system setting, still finishes with Done. When no project file changed, Done closes the task with no commit and no leftover branch. The task’s results record what changed outside and how to undo it.

1. Start the task as usual

   The agent still gets a task folder, even if it will not change anything in it.

2. Make the outside change

   For example, a launcher file in ~/.local/share/applications/ or a shortcut on the desktop.

3. Write it down in the results

   Under What changed: each outside path, what it was before and after, and the exact steps to undo it. This is the only record, because Ishoo does not track files outside the project.

4. Done

   With nothing changed in the project, Done says the task closed with no file changes. Main gets no commit and no ishoo/<id> branch is left behind.

Proof of done

Ishoo checks work by freezing the exact version that would land and requiring check results recorded against that version. Checks are invariant (never waivable), required (must pass, or be waived by a person) or advisory (reported only). Any change afterwards means checking again.

Your agent chooses the checks for a task (for example: the tests, the linter, the site build), runs them, and records each result with the command and what it printed.

The change-size limit

Ishoo blocks a change that touches too much at once: by default, five or more parts of the project or eight or more source files. Three parts or five files lands with a warning. A blocked task is split into smaller tasks, each landed on its own.

Big changes are where agents make the mistakes nobody notices. Keeping each landing small keeps each one reviewable and easy to undo.

A project can set this check to Require (the default), Warn (measure and advise, never block) or Off.

Code review

Ishoo can ask your agent to get an independent code review before landing: a second, fresh context reads the change. The Require code review switch is in Settings, under Workflow. It is off by default because it costs noticeably more to run.

With Require code review on, your agent is told to have a separate, fresh context review its change before landing. That catches more mistakes, at the cost of more usage on your AI plan.

With it off, Ishoo says nothing about review at all. Either way, the review is recorded as advice, not as a check that can block a landing.

Undoing a landing

You undo a landed Ishoo task by asking your agent to preview a restore of it. The preview shows exactly which files would change. Applying it adds one new commit that returns the project to that point; history is kept and nothing is force-pushed.

1. Preview

   Ishoo shows the target version, the files that would change, and the tasks that would reopen. Nothing is changed.

2. Apply

   Only after you confirm. Ishoo adds one new commit whose files match the chosen point, on top of everything else.

Your data

Ishoo stores its records inside your project’s Git repository on your computer, with no Ishoo account or server. If the project has a Git remote, Ishoo publishes its history there too, so anyone with access to that repository can read it.

Where records live

Ishoo keeps one small file per task, decision and person under .ishoo/records in your project. That folder is ignored by your main branch; its history is saved on a separate Git ref, refs/ishoo/store, so your code history never fills up with record changes.

In plain terms: your records live in your project, but out of your code’s way. git log on your code shows only code changes, while every change to a task or decision is still saved with full history.

Backup and sync

Ishoo publishes your records to your project’s Git remote in the background as they change. The chip at the top right shows the state, such as Up to date or Not backed up; clicking it shows details, a button to check for or bring in updates, and a one-file backup.

Click the chip for the details: when each part was last published, and one button. Catch up now brings in newer work when that’s safe; Check for updates checks the remote. When catching up needs a Git decision, the button is greyed out and Ishoo gives you a message to copy to your agent instead.

Back up project to a file… writes the whole project, code history and records together, to one file wherever you choose. It can rebuild a working project in a new, empty folder.

Export

You export from Settings → Export: everything as one ZIP, everything as a folder of readable files, all tasks as one Markdown file, or all decisions as one Markdown file. Export keeps working after a trial ends, so your records are never locked away.

For your agent

Ishoo gives AI coding agents 34 MCP tools for plans, tasks, decisions, checks, landing and undo, sends them its working rules when they connect, tells them the next step and why, and refuses actions that skip a required step.

Everything an agent does in Ishoo goes through typed tools, never through editing files or scraping text. That’s what makes the record trustworthy: the tools check each step, and the agent can’t skip them.

The rules agents get

Ishoo sends a connecting agent its working rules automatically, and the agent can re-read them any time with ishoo_brief. The rules cover how to pick work, the scope and results every task needs, how to verify, and how to land.

• Use Ishoo’s tools for all task, plan and decision work. If they’re missing, stop and ask; never fall back to a homemade to-do file.
• Read the decisions that govern a task before changing code, and don’t contradict an accepted one.
• Work on one task at a time, from its own workspace.
• Test the real thing and report the command, what it printed and the exit code. Say “built, not tested” when that’s the truth.
• When a Git choice has a real tradeoff, pass Ishoo’s question to the person unchanged and do only the option they pick.

The next step, with a reason

An agent calls ishoo_status to learn what it’s working on, which decisions apply, whether scope and results are complete, the backup state, and a suggested next step with its reason. Your request always comes first; the suggestion is advice.

The suggestion follows fixed rules: an urgent task first, then the front of the active plan, never a blocked task. If the agent picks something else, it’s told to say why.

To compare work across plans, an agent can ask for a short list of candidates matching a theme, such as “safety” or “first launch”. That search matches meaning, not just words, and leaves out blocked tasks.

Guard rails

Ishoo refuses the step itself: a task can’t be filed without its scope, started while blocked, or landed with missing results, failed required checks, uncommitted changes or an oversized change. Each refusal says exactly what’s missing.

Ishoo relies on gates, not promises. Asking an agent to be careful is not enough; the tool refuses until the step is done, and tells the agent precisely what to fix.

If an agent tries to commit or push directly on a task it doesn’t own, bypassing Ishoo, a guard blocks it and the status shows an alert. The way out is always to go back through Ishoo’s steps.

All 34 tools

Ishoo provides 34 MCP tools: orientation (status, brief, show, list, candidates), tasks (new, edit, resolve, comment, split, retire), plans, decisions, the work lifecycle (start, stop, handoff, done, hotfix), verification, undo, people, projects, license and maintenance.

Tools that cover a whole area, such as ishoo_plan or ishoo_decision, take an operation name (op), so there are few tools to learn but nothing is missing.

Advanced

Ishoo’s advanced features are linked projects for work that spans several repositories, versions and releases, quick fixes that skip the full task steps for tiny changes, maintenance tools that diagnose and repair a project, and the full command-line reference.

You won’t need these on day one. They’re here for bigger projects, teams, and the rare day something goes wrong.

Linked projects

Ishoo can link a project to up to 10 related projects, such as a library your app depends on. Plans can then include tasks from a linked project, and agents can find every Ishoo project on the computer. Each project’s work still lands through its own tasks.

Linking is for coordination, not for managing a portfolio. A link records a short key, a readable label, and where the other project lives on this computer. Ask your agent to link, relink (when the folder moved) or unlink a project.

When one change needs work in two repositories, the agent splits it into one task per repository, and each goes through that repository’s own start-to-land steps.

Versions and releases

Ishoo can read your project’s version from a file you choose and show it in the top bar. Each task then records whether it is a patch, minor or major change. The version itself only changes when you deliberately release, and each release appears on the timeline.

Most projects don’t need this. Once a version file is set up (for example Cargo.toml or package.json), the current version shows in the top bar on every view.

Quick fixes

Ishoo has a quick-fix path for tiny changes, called hotfix: the agent names the exact files it changed, and Ishoo commits them, pushes, and files a finished task labeled hotfix in one step. Any other changed file blocks it.

Use it for a typo, a one-line fix, a wrong colour: things where writing a full scope would take longer than the fix. It still leaves a record, a done task labeled hotfix, so nothing changes silently.

Maintenance

Ishoo’s maintenance tools are run by your agent: doctor diagnoses and can repair the project’s records, lint checks them for problems, preflight shows whether a task is ready to land, cleanup removes leftovers from crashed sessions, and take over moves a task from an absent owner.

Ask your agent, for example: “Run Ishoo’s doctor on this project and tell me what it finds before fixing anything.”

From a terminal, ishoo backup create writes a one-file backup of the whole project and ishoo backup restore rebuilds it in a new folder, the same as the button on the backup chip.

Command-line reference

The ishoo command line mirrors the app and the agent tools: setup, tasks, plans, decisions, the work steps from start to done, people, linked projects, versions, backup and maintenance. Agents use the MCP tools instead; the command line is for people and scripts.

Every command below is listed from Ishoo’s own code, so this page can’t fall out of date without a test failing. Run ishoo <command> --help for the full options.