Stabilizing on aitasks

Kanban Board

Mon, 01 Jan 0001 00:00:00 +0000

The ait board command launches an interactive terminal-based kanban board for managing your tasks visually. Built with Textual, it provides a full-featured TUI with columns, task cards, inline metadata editing, git integration, and keyboard-driven navigation.

The ait board kanban view with task cards organized into columns

How-To Guides

Mon, 01 Jan 0001 00:00:00 +0000

How to Organize Tasks into Columns

Moving a task to a different column:

Focus the task card using arrow keys
Press Shift+Right to move it to the next column, or Shift+Left to move it to the previous column

The task is appended to the end of the target column. Column order follows the configured order, with “Unsorted / Inbox” on the far left. Collapsed columns are skipped when moving tasks.

How-To Guides

Mon, 01 Jan 0001 00:00:00 +0000

How to Navigate Files in the Tree

Press Tab to focus the file tree (if not already focused)
Use Up / Down arrows to move between files and directories
Press Enter or click a file to open it in the code viewer
Directories expand and collapse as you navigate into them

The tree shows only git-tracked files, automatically excluding __pycache__, node_modules, and .git directories. Dotfiles (like .gitignore) are included.

How to Navigate Code

Once a file is open in the code viewer:

How-To Guides

Mon, 01 Jan 0001 00:00:00 +0000

How to Start the Monitor

Recommended — via ait ide:

ait ide

This is the one-command path to the ait tmux IDE. ait ide resolves the tmux session name from tmux.default_session in project_config.yaml (defaulting to aitasks), creates or attaches to that session, and opens a monitor window inside it. Because it always passes an explicit session name, the session-rename dialog never fires.

Standalone — from inside an existing tmux session:

ait monitor

Run this from within a tmux session you already have open. Monitor attaches to the current session.

/aitask-pickrem

Mon, 01 Jan 0001 00:00:00 +0000

A mostly autonomous version of /aitask-pick designed for non-interactive environments. It combines task selection and implementation into a single flow with zero AskUserQuestion calls — all decisions are driven by an execution profile. The only interactive step is plan approval, which still requires the user to review and confirm the implementation plan via ExitPlanMode.

Note: This skill requires write access to the task data branch, so it is suited for local Claude Code or CI-like environments. For Claude Code Web (which cannot write to branches other than the code branch), use /aitask-pickweb instead.

/aitask-pickweb

Mon, 01 Jan 0001 00:00:00 +0000

A sandboxed version of /aitask-pickrem designed specifically for Claude Code Web, where the environment has no push access to aitask-locks, aitask-data, or main branches. It combines task selection and implementation into a single flow with zero AskUserQuestion calls — all decisions are driven by an execution profile. The only interactive step is plan approval, which still requires the user to review and confirm the implementation plan via ExitPlanMode.

All task metadata (plans, completion markers) is stored in .aitask-data-updated/ on the current working branch. After the Claude Web session completes, run /aitask-web-merge locally to merge code to main and archive the task.

Monitor

Mon, 01 Jan 0001 00:00:00 +0000

The ait monitor command launches an interactive TUI that shows every pane in the current tmux session, categorized as code agents, TUIs, or other panes, with a live preview of the focused pane and keystroke forwarding. It is the dashboard of the ait tmux-based development environment: from a single window you can watch agents work, jump to any other TUI, and interact with running processes without leaving the monitor.

Tutorial

Launching the Monitor

The recommended way to start monitor is via ait ide:

/aitask-explore

Mon, 01 Jan 0001 00:00:00 +0000

Explore the codebase interactively with guided investigation, then create a task from findings. This skill bridges the gap between “I think something needs work” and a well-defined task with context.

Usage:

/aitask-explore [--profile <name>]

The optional --profile <name> argument overrides execution-profile selection for this invocation, mirroring /aitask-pick --profile.

Note: Must be run from the project root directory. See Skills overview for details.

Codex CLI note: When continuing from this skill into implementation, in Codex wrappers, after implementation, most of the times you will need to explicitly tell the agent to continue the workflow because request_user_input is only available in plan mode. Example prompts: Good, now finish the workflow or Good, now continue.

Code Browser

Mon, 01 Jan 0001 00:00:00 +0000

The ait codebrowser command launches an interactive terminal-based code browser for exploring project files with task-aware annotations. Built with Textual, it provides syntax-highlighted file viewing, a git-aware file tree, and an annotation gutter that maps lines of code to the aitasks that introduced them — powered by the explain data pipeline.

The ait codebrowser with file tree (left) and syntax-highlighted code viewer (right)

How-To Guides

Mon, 01 Jan 0001 00:00:00 +0000

Change the Default Model for an Operation

Open the Settings TUI: ait settings
Press a to go to the Agent Defaults tab
Navigate to the operation you want to change (e.g., task-pick)
Press Enter to open the agent/model picker
Step 1: Select the code agent (claudecode, geminicli, codex, opencode)
Step 2: Select the model from the list, then choose the target layer:
- Project – Saves to codeagent_config.json (shared, git-tracked)
- User – Saves to codeagent_config.local.json (personal, gitignored)
The change takes effect immediately

Note: Choosing User layer means this override only applies to your machine. Other team members will continue using the project default.

Feature Reference

Mon, 01 Jan 0001 00:00:00 +0000

Keyboard Shortcuts

Key	Action	Context
`q`	Quit the application	Global
`Tab`	Toggle focus between search box and board	Global
`Escape`	Return to board from search / dismiss modal	Global
`Up`	Navigate to previous task in column	Board
`Down`	Navigate to next task in column	Board
`Left`	Navigate to previous column	Board
`Right`	Navigate to next column	Board
`Enter`	Open task detail dialog	Board (focused card)
`r`	Refresh board from disk	Board
`s`	Sync task data with remote	Board
`O`	Open board options/settings dialog	Board
`a`	Switch to All view (show all tasks)	Board
`g`	Switch to Git view (show git-linked tasks)	Board
`i`	Switch to Implementing view (show implementing tasks + context)	Board

Task Operations

Key	Action	Context
`Shift+Right`	Move task to next column (skips collapsed)	Board (parent cards only)
`Shift+Left`	Move task to previous column (skips collapsed)	Board (parent cards only)
`Shift+Up`	Swap task with one above	Board (parent cards only)
`Shift+Down`	Swap task with one below	Board (parent cards only)
`Ctrl+Up`	Move task to top of column	Board (parent cards only)
`Ctrl+Down`	Move task to bottom of column	Board (parent cards only)
`n`	Create a new task	Board
`x`	Toggle expand/collapse child tasks	Board (parent or child card)
`c`	Commit focused modified task	Board (shown when task is modified)
`C`	Commit all modified tasks	Board (shown when any task is modified)
`p`	Pick the focused task (start implementation)	Board (context-dependent — shown when task is pickable)
`b`	Launch brainstorm for the focused task	Board (context-dependent — shown when task is brainstormable)

Column Operations

Key	Action	Context
`Ctrl+Right`	Move column one position right	Board
`Ctrl+Left`	Move column one position left	Board
`X` (Shift+X)	Toggle collapse/expand for focused card’s column	Board (focused card)
`Ctrl+Backslash`	Open command palette	Global
Click `▼` / `▶`	Toggle column collapse/expand	Column header
Click `✎`	Open column edit dialog	Column header

Key	Action	Context
`Up`	Focus previous field	Inside modal dialogs
`Down`	Focus next field	Inside modal dialogs
`Left`	Cycle to previous option	On CycleField
`Right`	Cycle to next option	On CycleField
`Enter`	Activate focused button / navigate to linked task	Inside modal dialogs
`Escape`	Close the dialog	Inside modal dialogs

Task Card Anatomy

┌─────────────────────────────────┐ ← Border color = priority
│ t47 * playlists support │ ← Task number (cyan), * if modified (orange), title (bold)
│ 💪 medium | 🏷️ ui,api | GH | PR:GH | @alice │ ← Effort, labels, issue/PR indicator, contributor
│ 🔒 alice@example.com │ ← Lock indicator (if locked)
│ 🚫 blocked | 👤 alice │ ← Status/blocked, assigned to
│ 🔗 t12, t15 │ ← Blocking dependency links
│ 📎 folded into t42 │ ← Folded indicator (if applicable)
│ 👶 3 children │ ← Child task count (if parent)
└─────────────────────────────────┘

Not all lines are shown on every card — lines only appear when the corresponding data exists.

Feature Reference

Mon, 01 Jan 0001 00:00:00 +0000

Keyboard Shortcuts

Application

Key	Action	Context
`q`	Quit the application	Global
`Tab`	Cycle focus between file tree, code viewer, and detail pane	Global
`r`	Refresh explain annotations for current file’s directory	Global
`t`	Toggle annotation gutter visibility	Global
`g`	Open go-to-line dialog	Global
`e`	Launch the configured code agent for explain on the current file	Global
`d`	Toggle detail pane visibility	Global
`D`	Toggle detail pane between default and expanded width	Global
`h`	Toggle completed tasks history view	Global
`H`	Open history screen navigated to the task at cursor	Global (requires annotated line)

History Screen

Key	Action	Context
`h` / `Escape`	Return to code browser	History screen
`v`	Toggle task/plan content view	History screen
`l`	Open label filter dialog	History screen
`Tab`	Cycle focus between list and detail panes	History screen
`Left`	Move focus to list pane (cycles task list / recently opened)	History screen
`Right`	Move focus to detail pane	History screen
`Up` / `Down`	Navigate between focusable fields	History detail
`Enter`	Open link, select task, or navigate to file (context-dependent)	History detail
`s`	Open sibling task picker (on child tasks)	History detail
`a`	Launch QA agent for the selected task	History detail

Label Filter Dialog

Key	Action	Context
`Escape`	Cancel and close dialog	Dialog
`o`	Confirm selection (OK)	Dialog
`r`	Reset filter (show all)	Dialog

Sibling Picker Dialog

Key	Action	Context
`Escape`	Cancel and close dialog	Dialog
`Enter`	Select sibling task	Dialog

Code Viewer

Key	Action	Context
`Up`	Move cursor up one line	Code viewer
`Down`	Move cursor down one line	Code viewer
`Shift+Up`	Extend selection upward	Code viewer
`Shift+Down`	Extend selection downward	Code viewer
`Escape`	Clear selection	Code viewer
`n`	Create a task with `file_references` seeded from the selection or cursor line	Code viewer
`PageUp`	Move cursor up by one screen	Code viewer
`PageDown`	Move cursor down by one screen	Code viewer

Go-to-Line Dialog

Key	Action	Context
`Enter`	Jump to entered line number	Dialog
`Escape`	Cancel and close dialog	Dialog

Mouse Interactions

Action	Effect
Click on file tree entry	Select and open file
Click in code viewer	Position cursor at clicked line
Drag in code viewer	Select line range
Scroll wheel in code viewer	Scroll content

Annotation Data Pipeline

The codebrowser uses the same explain data pipeline as /aitask-explain:

Feature Reference

Mon, 01 Jan 0001 00:00:00 +0000

Keyboard Shortcuts

Key	Action	Context
`Tab`	Cycle focus to the next zone (pane list ↔ preview)	Global
`Shift+Tab`	Cycle focus to the previous zone	Global
`Up`	Focus the previous card in the pane list	Pane list zone
`Down`	Focus the next card in the pane list	Pane list zone
`q`	Quit monitor	Global

Pane Interaction

Key	Action	Context
`Enter`	Send an `Enter` keystroke to the focused tmux pane	Pane list zone
`Enter`	Send an `Enter` keystroke to the focused tmux pane	Preview zone
Any other key	Forwarded to the focused tmux pane (characters, Ctrl-combos, arrows, Escape)	Preview zone
`s`	Switch tmux focus to the focused pane (`tmux switch-client`)	Pane list zone
`i`	Show the task detail dialog for the focused agent pane (requires a task ID in the window name)	Pane list zone
`k`	Kill the focused pane after confirmation (`tmux kill-pane`)	Pane list zone
`n`	Pick the next ready sibling task for the focused agent pane	Pane list zone
`R`	Restart the task running in the focused agent pane	Pane list zone
`L`	Open the log for the focused pane in a separate viewer	Pane list zone

Monitor Controls

Key	Action	Context
`j`	Open the TUI switcher overlay	Global
`r`	Refresh the pane list and preview immediately	Global
`F5`	Refresh the pane list and preview immediately (alias for `r`, hidden in footer)	Global
`z`	Cycle the preview size through S / M / L presets	Global
`b`	Toggle the preview scrollbar visibility	Global
`t`	Scroll the preview to its tail (newest output)	Global
`a`	Toggle auto-switch mode (automatically focus idle agents needing attention)	Global
`M`	Toggle the multi-session view ON/OFF (see Multi-session view)	Global

Note: In the preview zone, every keystroke that is not handled by a global binding is forwarded to the tmux pane via tmux send-keys. Special keys (Enter, Escape, Backspace, arrows, Space, Delete, Home, End, PageUp/Down) and Ctrl-combinations are translated; regular characters are sent literally.

/aitask-fold

Mon, 01 Jan 0001 00:00:00 +0000

Identify and merge related tasks into a single task, then optionally execute it. This skill provides the same folding capability as /aitask-explore but as a standalone skill — no codebase exploration required.

Usage:

/aitask-fold # Interactive: discover and fold related tasks
/aitask-fold 106,108,112 # Explicit: fold specific tasks by ID

Note: Must be run from the project root directory. See Skills overview for details.

Codex CLI note: When continuing from this skill into implementation, in Codex wrappers, after implementation, most of the times you will need to explicitly tell the agent to continue the workflow because request_user_input is only available in plan mode. Example prompts: Good, now finish the workflow or Good, now continue.

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Keyboard Shortcuts

Global

Key	Action
a	Switch to Agent Defaults tab
b	Switch to Board tab
c	Switch to Project Config tab
t	Switch to Tmux tab
m	Switch to Models tab
p	Switch to Profiles tab
e	Export all configs
i	Import configs
r	Reload all configs from disk
q	Quit

Within Tabs

Key	Action	Context
Enter / Space	Edit field or cycle value	Agent Defaults, Board, Profiles
d / Delete	Remove user override	Agent Defaults
?	Toggle field description (summary/expanded)	Profiles
Escape	Close dialog or cancel	Modals

Tabs

Tab	Shortcut	Editable	Description
Agent Defaults	a	Yes	Default agent/model per operation, project and user layers
Board	b	Partially	Columns (read-only), user settings (editable)
Project Config	c	Yes	Shared values from `project_config.yaml` such as coauthor domain and build verification
Tmux	t	Yes	Tmux integration settings (session name, split direction, monitor options, git TUI)
Models	m	No	Available models per agent with verified scores
Profiles	p	Yes	Execution profiles that pre-answer workflow questions

Agent Defaults Operations

Operation	Description
`task-pick`	Model used for picking and implementing tasks
`explain`	Model used for explaining/documenting code
`batch-review`	Model used for batch code review operations
`raw`	Model used for direct/ad-hoc code agent invocations (passthrough mode)

Configuration Files

File	Scope	Editable via TUI	Description
`aitasks/metadata/codeagent_config.json`	Project	Yes (Agent Defaults)	Default agent/model per operation
`aitasks/metadata/codeagent_config.local.json`	User	Yes (Agent Defaults)	Per-user overrides (gitignored)
`aitasks/metadata/board_config.json`	Project	No	Board column definitions
`aitasks/metadata/board_config.local.json`	User	Yes (Board)	User board settings (gitignored)
`aitasks/metadata/project_config.yaml`	Project	Yes (Project Config)	Shared workflow settings such as coauthor domain and build verification
`aitasks/metadata/models_claudecode.json`	Project	No	Claude Code model definitions
`aitasks/metadata/models_geminicli.json`	Project	No	Gemini CLI model definitions
`aitasks/metadata/models_codex.json`	Project	No	Codex CLI model definitions
`aitasks/metadata/models_opencode.json`	Project	No	OpenCode model definitions
`aitasks/metadata/profiles/*.yaml`	Project	Yes (Profiles)	Execution profiles (git-tracked)
`aitasks/metadata/profiles/local/*.yaml`	User	Yes (Profiles)	User execution profiles (gitignored)

Profile Schema

Execution profiles are YAML files with the following keys. All keys are optional – omitted keys cause the corresponding question to be asked interactively.

Settings

Mon, 01 Jan 0001 00:00:00 +0000

Launching

ait settings

The Settings TUI requires the shared Python virtual environment (installed by ait setup) with the textual and pyyaml packages.

Understanding the Layout

The Settings TUI organizes configuration into five tabs, each accessible via a keyboard shortcut displayed in the footer.

Agent Defaults (a)

The Agent Defaults tab shows which code agent and model is configured for each operation

Stabilizing on aitasks

Kanban Board

How-To Guides

How to Organize Tasks into Columns

How-To Guides

How to Navigate Files in the Tree

How to Navigate Code

How-To Guides

How to Start the Monitor

/aitask-pickrem

/aitask-pickweb

Monitor

Tutorial

Launching the Monitor

/aitask-explore

Code Browser

How-To Guides

Change the Default Model for an Operation

Feature Reference

Keyboard Shortcuts

Board Navigation

Task Operations

Column Operations

Modal Navigation

Task Card Anatomy

Feature Reference

Keyboard Shortcuts

Application

History Screen

Label Filter Dialog

Sibling Picker Dialog

Code Viewer

Go-to-Line Dialog

Mouse Interactions

Annotation Data Pipeline

Feature Reference

Keyboard Shortcuts

Zone Navigation

Pane Interaction

Monitor Controls

/aitask-fold

Reference

Keyboard Shortcuts

Global

Within Tabs

Tabs

Agent Defaults Operations

Configuration Files

Profile Schema

Settings

Launching

Understanding the Layout

Agent Defaults (a)