Feature Reference
Keyboard shortcuts, annotation pipeline, and technical details
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 |
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 |
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
aiexplains/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 aiexplains/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 the configured code agent (when pressing e) |
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