Ishoo
Get Ishoo
Documentation

The Ishoo manual

Everything an agent or a human needs to set up and run Ishoo. Generated from README.md.

Ishoo lets AI code like a developer, not just an agent.

Built for AX: Agent Experience.

AI coding agents can write, edit, refactor, and run commands. But real development is more than making changes. It means understanding the project, following decisions, staying in scope, working from a plan, proving what changed, and leaving a clear record behind.

Ishoo gives your AI that structure.

Buy Ishoo, install it, and tell your coding agent to use it.

No hosted workspace. No subscription. No server to manage. No network connection required by Ishoo itself.

Use it with Claude Code, Codex, Gemini, Cursor, OpenCode, KiloCode, or a local model. Your AI gets a real way to work. Your project gets memory. You get a calm screen that shows what is happening without making you manage another system.

How do issues get made?

You talk to your AI.

Ishoo gives it somewhere proper to put the plan.

That is the whole idea.

You do not need to sit there filling out tickets like a project manager. Tell your coding agent what you want, what you already discussed, what files or docs matter, and where you want the project to end up.

Then ask it to use Ishoo.

For example:

Use the Ishoo MCP tools.

This is what I want to build:
[describe the goal]

These are the materials:
[mention specs, mockups, notes, SEMMAP output, prototypes, screenshots, docs, etc.]

Create the issues needed to get this project to a working version.
Include scope, decisions, blockers, and proof of done.

Your AI turns the conversation into real work: issues, named plans, decisions, scope contracts, and completion checks.

You review the plan. You adjust anything that feels wrong. Then the agent starts working.

Start messy. Work clean.

Ishoo does not replace your creative process.

Use whatever works before the build phase:

That early phase can stay loose.

Ishoo begins when the idea needs to become work.

Once your coding agent starts using Ishoo, the work gets structure: scoped issues, named plans, searchable project decisions, progress tracking, and proof of done.

What Ishoo gives your AI

Ishoo is a tool for your AI, not another AI tool.

It gives your agent the things a real developer would expect before changing code.

Issues

Clear units of work with enough context to act.

Plans

Named queues of work so the agent knows what comes next. New issues go into an explicit plan; Backlog stays the fallback, not the place new work silently disappears.

Decisions

Project memory. The important choices that future work should respect.

Decisions can be labeled and searched, so your agent can find the relevant rules instead of rereading every historical ADR.

Scope contracts

A clear boundary around what the agent is allowed to touch.

Proof of done

A concrete answer to: “How do we know this is finished?”

Progress tracking

A visible record of what is happening, what changed, what landed, and what still needs attention.

What you get

Ishoo is built to stay out of your way.

You should be able to glance at the app and understand the state of the project without digging through chat logs, terminal output, or half-finished plans.

You get:

The goal is simple:

Let the AI move fast, without letting the project turn into a mess.

Local-first by design

Ishoo does not need a hosted workspace.

It does not require an Ishoo account. It does not phone home to manage your work. It does not require a subscription to keep using your own project memory. It does not need a network connection of its own.

Your AI provider may need the internet. Claude Code, Codex, Gemini, Cursor, and similar tools may connect to their own services.

But Ishoo itself is local.

Use it with a local model, and Ishoo can be part of a fully local AI coding workflow.

Yes, that means you could use it off-grid in a cave.

AX: Agent Experience

UX is how software feels to humans.

DX is how software feels to developers.

AX is how software works for agents.

Agents are becoming real users of software. They need clear tools, stable context, structured state, safe boundaries, and useful feedback.

Most AI coding tools focus on giving humans a better way to prompt an AI.

Ishoo focuses on giving the AI a better way to work.

That is AX.

The basic workflow

1. Install Ishoo

Install the app and open it with your project.

2. Add your project materials

Put useful artifacts in the repo: specs, notes, prototypes, docs, SEMMAP output, screenshots, research, or anything else that explains what you are building.

3. Start your coding agent

Use the agent you already like.

Claude Code. Codex. Gemini. Cursor. OpenCode. KiloCode. A local model.

Ishoo is not trying to replace your agent.

It gives your agent a better way to work.

MCP-first setup

Ishoo includes an MCP server for agents:

{
  "mcpServers": {
    "ishoo": {
      "command": "ishoo",
      "args": ["mcp"]
    }
  }
}

This repo can register that server in .mcp.json. When your agent host supports MCP, it connects to ishoo mcp, receives concise Ishoo instructions automatically during initialization, and gets typed ishoo_* tools for status, plans, issues, decisions, comments, and gates.

That means the old practice of priming the agent with the CLI brief command is obsolete for agents. The full protocol is available as the ishoo_brief MCP tool for re-reading on demand, such as after context compaction. If the ishoo_* MCP tools are not available, configure the MCP server before asking the agent to operate Ishoo.

The MCP surface uses the same core behavior as the CLI. Agents can list and search decisions by label or text, inspect issue-relevant governing ADRs, start the next unblocked issue, and complete work through the same gates a human would use.

4. Tell the agent to use Ishoo

Start with:

Use the Ishoo MCP tools and follow the Ishoo protocol.
If the tools are not available, stop and ask me to enable the Ishoo MCP server.

Then explain what you want.

For example:

I want to get this project to a usable MVP.

Read the concept doc, KPI spec, and prototype HTML file.
Then create the issues needed to build it properly.

Make sure each issue has clear scope and proof of done.
Create decisions for any important product or technical choices.
Put the work in a sensible order.

5. Review the plan

Open Ishoo and look over what the agent created.

Adjust anything that feels off.

Each new issue belongs to a named plan. The Backlog is still there as a fallback and recovery surface, but new work should have a deliberate home.

6. Let the agent work

The agent can now work through scoped issues, follow the relevant decisions, report progress, and prove completion.

You can stay high-level without losing control.

What Ishoo is not

Ishoo is not a hosted project-management platform.

It is not Jira. It is not Linear. It is not Monday. It is not GitHub Issues with a new skin.

Those tools are built around human teams reporting and organizing work in a shared cloud workspace.

Ishoo is built around AI agents doing work inside a real codebase.

It is local. It is agent-friendly. It is meant to be used by the tools already doing the coding.

Why not just use a normal issue tracker?

Normal issue trackers assume humans are the main operators.

They ask humans to create tickets, update status, maintain labels, write acceptance criteria, move cards, and keep the system clean.

Ishoo assumes the agent should do most of that clerical work.

You talk through the goal. The agent creates the issues. Ishoo keeps the work structured. You review and steer.

That is the difference.

Scope contracts

AI agents are most useful when the work is bounded.

Ishoo encourages each issue to have a clear scope contract:

**Concrete change:** What should change?
**Main surface:** Where should the work happen?
**Proof of done:** How do we know it is finished?
**Out of scope:** What should the agent avoid touching?

This keeps issues small, reviewable, and easier for the agent to complete correctly.

A vague task like this:

Improve onboarding

becomes something the agent can actually work on:

**Concrete change:** Add the first-run project setup screen.
**Main surface:** desktop onboarding flow.
**Proof of done:** A new user can open Ishoo, select a project, and see the initial dashboard.
**Out of scope:** Account systems, cloud sync, pricing, or documentation site changes.

Decisions

Decisions are project memory.

They capture the important choices your AI should not forget:

Decisions are not just a long archive. Ishoo supports a small controlled set of decision labels, such as workflow, store, git, scope, agent-surface, and product. The agent can filter decisions by label or search across their titles, bodies, and tags.

ishoo decision list --label workflow
ishoo decision list --text "scope gate"

When future work begins, your agent sees the governing ADRs attached to the issue and any decisions relevant to that issue's labels. If there is no relevance signal yet, Ishoo falls back to the full accepted decision rail rather than hiding governance.

A project without decisions slowly forgets itself.

Ishoo gives it memory.

Proof of done

“Done” should mean more than “the agent stopped editing files.”

Ishoo encourages every issue to define proof of done before the work starts.

That proof can be a test, a build check, a UI behavior, a file change, a manual verification step, or a specific outcome.

The point is simple:

The agent should know what finished means.

On real execution work, ishoo done commits the scoped work, runs the configured correctness gate, checks execution-diff size, fast-forwards main, records the completed issue, and tears down the temporary claim/worktree. If the work is too broad, Ishoo points the agent toward decomposition instead of letting one issue sprawl.

Example agent prompts

Create a project plan

Use the Ishoo MCP tools.

Read the project materials in this repo.
Create the issues needed to get to a working MVP.

Use small, scoped issues.
Create decisions for important product or technical choices.
Add proof of done to each issue.
Put the issues in a sensible order.

Turn a prototype into work

Use the Ishoo MCP tools.

The HTML prototype shows the intended product behavior and visual direction.
Use it as a product reference, not as final architecture.

Create the issues needed to implement this properly in the app.
Preserve the core interaction model.
Call out any decisions we need to make before coding.

Continue from a previous conversation

Use the Ishoo MCP tools.

Here is what we already discussed:
[paste summary]

Here is the goal:
[describe target]

Create or update the Ishoo issues needed to get there.
Do not start coding until the plan is clear.

Work the next issue

Use the Ishoo MCP tools.

Pick the next ready issue from Ishoo.
Respect its scope.
Follow project decisions.
Make the smallest clean change that satisfies proof of done.
Run the required checks before marking it complete.

Search the project's decisions

Use the Ishoo MCP tools.

Find the governing decisions for this issue.
If the issue has labels, use them to narrow the ADRs.
If the decision rail looks incomplete, fall back to the full accepted set before coding.

How Ishoo fits with SEMMAP Labs

Ishoo is part of a broader idea: AI coding works better when agents have structure.

During development those tools can remain separate repositories. Ishoo's execution worktrees resolve sibling path dependencies so the local build gate works without turning the whole ecosystem into one development repo. Shipping can still package the pieces together for users.

The thesis is simple:

AI coding does not just need smarter models.

It needs better working conditions.

Ishoo gives your AI those working conditions.

The promise

Ishoo gives AI coding rails you do not have to manage.

You do not need to babysit every edit. You do not need to maintain a second cloud workspace. You do not need to turn yourself into a project manager.

Tell your AI what you want.

Let Ishoo give it somewhere proper to put the plan.

Then watch the work move.