Help & setup guide

Everything you need to get started with Aisman.

Getting started

1. Launch Aisman — Navigate to /dashboard in your browser.
2. Create a project — Type a project name in the filter box and press Enter.
3. Set the root folder — Point to your project's root directory on your local machine. Aisman creates a .aisman folder there for instructions and file exchange.
4. Configure your host — Go to Settings → Host Instructions, select your host, and insert the Aisman instructions header.

Projects

Each project corresponds to a codebase you're working on. The project detail view shows:

• Stats — Total issues, implemented count, total sessions, and total steps.
• Details tab — Project name, acronym, description, root folder path.
• AI Outputs tab — Detected output files from the .aisman/outputs/ directory on your machine.

Workflow (4 steps)

Step 1: Select issues

Choose which existing issues to include in this AI session step. You can also write new free-form instructions — the agent will decompose them into discrete issues.

Step 2: Instructions

Add context, special requirements, or constraints. The text is included verbatim in the generated prompt. Supports Markdown with live preview.

Step 3: Generate

Aisman generates a structured instruction prompt containing your selected issues with their full context (parent hierarchy, notes, relationships) plus free-form instructions. The prompt file is saved in .aisman/inputs/ and automatically copied to your clipboard.

Step 4: Process output

When your model completes its task, it drops a JSON result file into .aisman/outputs/. Aisman auto-detects the file, parses it, updates task statuses, creates new issues, and records session history automatically.

Issues

Issues are created automatically by the model from your free-form text. Each issue has:

• Type — Feature, Bug, Task, Improvement, etc.
• Reason — Why it was created (new feature, split from parent, bug found, etc.).
• Status — Not started, In progress, Implemented, Confirmed, etc.
• Notes — User notes and AI responses, with cross-references (n1, n2...).
• Relations — Dependencies, extensions, parent-child links to other issues.

AI sessions

Sessions group related work steps. Each step represents one round of agent interaction. Sessions are owned by the user who created them — only the creator can continue a session in the Workflow tab.

Session issues

The Session issues tab shows every issue linked to the session via the SessionIssue table. Each entry displays a touch count indicating how many steps interacted with that issue:

• N/A — The issue was manually added to the session and has not been touched by any step yet (touch count = 0).
• 1 step — The issue was processed in exactly one step and was not directly created in a step (i.e. it existed before and was referenced).
• N steps — The issue was touched by N steps (includes being created in a step).

Adding issues to a session

Click the Add issues button on a session you own to enter add-issue mode. In this mode:

• A checkbox appears next to every issue across all panels (issues list, session step issues, session issues).
• Issues already in the session are pre-checked; those with a touch count > 0 are disabled (cannot be removed).
• Check or uncheck issues to add/remove them. Changes are synced across all visible views.
• Click Confirm to save your changes, or Cancel to discard them.

Session steps

Each step shows per-step outcomes and metrics:

• Session step issues created in that step
• Counters for created, not started, in progress, and completed issues

Settings

Host Instructions

Manage the instruction files for each supported host. The instructions tell the model about Aisman's input/output format and how to create/update issues.

Aisman Instructions (Template)

The master template for the .aisman/instructions.md file. Contains replacement tokens (like {{STATUSES}}, {{TYPES}}) that are filled with your project's actual data when rendered.

General Settings

Configure instruction mode (automatic per tool or custom file), and other application-wide settings.

Auto-detection

When a project root is set, Aisman uses the browser's File System Access API to scan <project root>/.aisman/outputs/ for new JSON files. Detected files appear in the project detail panel with a notification badge.

Supported hosts

Host	Instructions File	Auto-Detect
GitHub Copilot	.github/copilot-instructions.md	Via .aisman/outputs
Cursor	.cursor/rules	Via .aisman/outputs
Claude Code	CLAUDE.md	Via .aisman/outputs
Windsurf	.windsurfrules	Via .aisman/outputs
RooCode	.roo/rules	Via .aisman/outputs
KiloCode	.kilocode/rules	Via .aisman/outputs
Continue	.continue/config.json	Via .aisman/outputs
Aider	.aider/conventions.md	Via .aisman/outputs
Codeium	.codeium/instructions.md	Via .aisman/outputs
Custom	User-defined path	Via .aisman/outputs