# Makima View Command
The `makima view` command provides an interactive Terminal User Interface (TUI) for browsing and managing tasks, contracts, and files in the makima system.
## Overview
The view command offers a fuzzy-searchable interface inspired by tools like [fzf](https://github.com/junegunn/fzf) and [try](https://github.com/tobi/try). It allows you to quickly navigate through your makima entities using keyboard shortcuts and real-time filtering.
## Usage
```bash
# Browse tasks interactively
makima view tasks
# Browse contracts with an initial search query
makima view contracts "my project"
# Browse files without preview pane
makima view files --no-preview
# Browse tasks for a specific contract
makima view tasks --contract-id <uuid>
# Change directory to selected task's worktree (shell integration)
cd $(makima view tasks)
```
## Subcommands
| Subcommand | Description |
|------------|-------------|
| `tasks` | Browse tasks with status indicators and progress summaries |
| `contracts` | Browse contracts with phase and status information |
| `files` | Browse contract files with content preview |
## Options
| Option | Environment Variable | Description |
|--------|---------------------|-------------|
| `--api-url` | `MAKIMA_API_URL` | API URL for the makima server (default: `https://api.makima.jp`) |
| `--api-key` | `MAKIMA_API_KEY` | API key for authentication |
| `--contract-id` | `MAKIMA_CONTRACT_ID` | Filter results to a specific contract |
| `--no-preview` | - | Disable the preview pane |
| `--sort` | - | Sort order: `recent` (default), `name`, or `status` |
## Keyboard Shortcuts
### Navigation
| Key | Action |
|-----|--------|
| `↑` / `k` | Move selection up |
| `↓` / `j` | Move selection down |
| `Page Up` | Move up one page |
| `Page Down` | Move down one page |
| `Home` | Go to first item |
| `End` | Go to last item |
### Actions
| Key | Action |
|-----|--------|
| `Enter` | View/select the highlighted item |
| `e` | Open in editor (uses `$EDITOR` environment variable) |
| `d` | Delete item (with confirmation prompt) |
| `c` | Navigate to task's worktree (outputs path for `cd`) |
| `Tab` | Toggle preview pane visibility |
| `Ctrl+r` | Refresh data from server |
### Search
| Key | Action |
|-----|--------|
| `/` | Focus search input |
| `Esc` | Clear search / cancel |
| (typing) | Filter items in real-time |
### General
| Key | Action |
|-----|--------|
| `q` | Quit the TUI |
| `?` | Show help overlay |
| `1` / `2` / `3` | Switch view mode (Tasks/Contracts/Files) |
## Features
### Fuzzy Search
The search uses the SkimMatcherV2 algorithm, providing:
- **Smart case matching**: Case-insensitive by default, case-sensitive if pattern contains uppercase
- **Word boundary bonuses**: Matches at word boundaries score higher
- **Consecutive character bonuses**: Consecutive matches score higher
- **Multi-term search**: Space-separated terms all must match (e.g., "fix bug" matches items containing both "fix" and "bug")
### Recency Sorting
When using the default `recent` sort order, items are sorted by last update time. The fuzzy search also applies a recency bonus, so recently modified items rank higher even with slightly lower match scores.
### Preview Pane
The preview pane (toggled with `Tab`) shows detailed information about the selected item:
- **Tasks**: Name, status, plan, progress summary, worktree path
- **Contracts**: Name, phase, status, task counts, repository info
- **Files**: Name, type, content preview (markdown rendered)
### Status Indicators
Tasks display visual status indicators:
| Icon | Status |
|------|--------|
| `▸` | Running |
| `✓` | Done |
| `✗` | Failed |
| `○` | Pending |
| `⏸` | Paused |
| `⊘` | Blocked |
## Shell Integration
### Change to Task Worktree
The view command can output the selected item's path for shell integration:
```bash
# Change to selected task's worktree
cd $(makima view tasks)
# Or create a shell function
function mcd() {
local path=$(makima view tasks "$@")
if [ -n "$path" ]; then
cd "$path"
fi
}
```
### Open in Editor
The `e` key opens the selected item in your configured editor:
```bash
# Set your preferred editor
export EDITOR=code # VS Code
export EDITOR=vim # Vim
export EDITOR=nano # Nano
```
## Examples
### Browse Running Tasks
```bash
makima view tasks "running"
```
### Find a Specific Contract
```bash
makima view contracts "authentication"
```
### Quick Task Navigation
```bash
# Jump to a task directory with fuzzy search
cd $(makima view tasks "api endpoint")
```
## Architecture
The view command is built using:
- **[ratatui](https://github.com/ratatui/ratatui)**: TUI rendering framework
- **[crossterm](https://github.com/crossterm-rs/crossterm)**: Cross-platform terminal manipulation
- **[fuzzy-matcher](https://github.com/lotabout/fuzzy-matcher)**: SkimMatcherV2 fuzzy matching algorithm
### Module Structure
```
makima/src/daemon/
├── cli/
│ └── view.rs # CLI argument definitions
└── tui/
├── mod.rs # Module exports
├── fuzzy.rs # Fuzzy matching wrapper
├── app.rs # Application state (TODO)
├── event.rs # Event handling (TODO)
├── ui.rs # UI rendering (TODO)
├── widgets/ # Reusable components (TODO)
└── views/ # View-specific logic (TODO)
```
## Troubleshooting
### Terminal Compatibility
The TUI requires a terminal that supports:
- ANSI escape codes
- Alternate screen buffer
- Mouse events (optional)
Most modern terminals (iTerm2, Terminal.app, Windows Terminal, Alacritty, kitty) are supported.
### Small Terminal Windows
If your terminal is too small, use `--no-preview` to disable the preview pane and maximize the list area.
### API Connection Issues
If you see connection errors, verify:
1. `MAKIMA_API_URL` is set correctly
2. `MAKIMA_API_KEY` is valid
3. Network connectivity to the server
## See Also
- [makima supervisor](./supervisor-commands.md) - Task orchestration commands
- [makima contract](./contract-commands.md) - Contract interaction commands
- [makima daemon](./daemon.md) - Daemon configuration
