Feature Reference
Keyboard shortcuts, annotation pipeline, and technical details
Maturity:
Depth:
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:
- When a file is selected, the
ExplainManagerchecks for cached explain data for the file’s directory - If no cache exists, it runs
aitask_explain_extract_raw_data.sh --gather --source-key <dir_key>targeting direct child files of the directory - Output is stored under
.aitask-explain/codebrowser/<dir_key>__<timestamp>/containing:reference.yaml— Structured line-to-commit-to-task mappingfiles.txt— List of analyzed filestasks/andplans/— Extracted task and plan files for context
reference.yamlis parsed to build annotation ranges (start line, end line, task IDs, commit hashes)- Annotations are rendered as color-coded task IDs in the gutter column of the code viewer
The dir_key identifies the source directory (e.g., aiscripts__lib for .aitask-scripts/lib/). Root-level files use the key _root_.
Explain Run Management
Explain data generated by the codebrowser is stored under .aitask-explain/codebrowser/, separate from top-level /aitask-explain runs. On startup, the codebrowser cleans up stale runs — for each directory key, only the newest run is kept.
You can also manage runs manually:
# List all runs (top-level and codebrowser)
ait explain-runs --list
# Interactive deletion with fzf
ait explain-runs
# Remove stale runs (keep newest per source directory)
ait explain-runs --cleanup-stale
See ait explain-runs and ait explain-cleanup for the full command reference.
Environment Variables
| Variable | Default | Purpose |
|---|---|---|
TERMINAL | Auto-detected | Terminal emulator for launching code agents (when pressing e or a) |
PYTHON | python3 | Python interpreter (used by launcher if shared venv is unavailable) |
Terminal auto-detection order: $TERMINAL, then alacritty, kitty, ghostty, foot, x-terminal-emulator, xdg-terminal-exec, gnome-terminal, konsole, xfce4-terminal, lxterminal, mate-terminal, xterm.
Requirements
- Python venv at
~/.aitask/venv/with packages:textual,pyyaml - Falls back to system
python3if venv not found (warns about missing packages) - Git repository (uses
git rev-parse --show-toplevelandgit ls-files) - Checks terminal capabilities and warns on legacy terminals
Next: Settings — the configuration editor for agents, models, and profiles.