1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
# 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
|
