# 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