Skip to content

Commit 9cc491e

Browse files
Data-Wiseclaude
Data-Wise
and
claude
authored
docs: add Phase 2 command documentation (#41)
Add missing command documentation (Phase 2): - flow.md - Main CLI dispatcher with all subcommands - hop.md - Quick project switch with tmux - pick.md - Interactive project picker - timer.md - Focus and break timers - morning.md - Daily startup routine Update mkdocs.yml navigation to include new commands. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
1 parent e61d2fa commit 9cc491e

File tree

6 files changed

+966
-0
lines changed

6 files changed

+966
-0
lines changed

‎docs/commands/flow.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# flow
2+
3+
> Unified CLI dispatcher for all flow-cli commands
4+
5+
The `flow` command is the main entry point for the flow-cli plugin. It provides access to all subcommands through a unified namespace.
6+
7+
---
8+
9+
## Usage
10+
11+
```bash
12+
flow <command> [args]
13+
```
14+
15+
## Getting Help
16+
17+
```bash
18+
flow help # Show all commands
19+
flow help <command> # Help for specific command
20+
flow help --list # List all commands
21+
flow help --search <term> # Search commands
22+
```
23+
24+
---
25+
26+
## Command Categories
27+
28+
### Core Workflow
29+
30+
| Command | Description |
31+
| ---------------------- | ------------------------------ |
32+
| `flow work <project>` | Start focused work session |
33+
| `flow pick [category]` | Interactive project picker |
34+
| `flow dash [scope]` | Project dashboard |
35+
| `flow finish [note]` | End session, optionally commit |
36+
| `flow hop <project>` | Quick switch (tmux) |
37+
| `flow why` | Show current context |
38+
39+
### ADHD Helpers
40+
41+
| Command | Description |
42+
| ------------------- | -------------------------- |
43+
| `flow start`, `js` | Just start (picks for you) |
44+
| `flow stuck` | Get unstuck when blocked |
45+
| `flow focus <text>` | Set current focus |
46+
| `flow next` | What to work on next |
47+
| `flow break [min]` | Take a proper break |
48+
49+
### Capture & Track
50+
51+
| Command | Description |
52+
| ------------------- | ------------------------ |
53+
| `flow catch <idea>` | Quick capture to inbox |
54+
| `flow crumb <note>` | Leave breadcrumb |
55+
| `flow inbox` | View inbox |
56+
| `flow win <text>` | Log a win |
57+
| `flow goal [set n]` | Daily win goal tracking |
58+
| `flow status` | View/update .STATUS file |
59+
60+
### Context-Aware Actions
61+
62+
| Command | Description |
63+
| -------------- | ----------------------------- |
64+
| `flow test` | Run tests (auto-detects type) |
65+
| `flow build` | Build project |
66+
| `flow preview` | Preview output |
67+
| `flow sync` | Smart git sync |
68+
| `flow check` | Health check (lint, types) |
69+
| `flow plan` | Sprint/project planning |
70+
| `flow log` | Activity log |
71+
72+
### Timer & Routine
73+
74+
| Command | Description |
75+
| ------------------ | ----------------------- |
76+
| `flow timer [min]` | Start focus timer |
77+
| `flow morning` | Morning startup routine |
78+
79+
### Setup & Diagnostics
80+
81+
| Command | Description |
82+
| -------------- | --------------------------- |
83+
| `flow doctor` | Check dependencies & health |
84+
| `flow setup` | Interactive setup wizard |
85+
| `flow install` | Install tools |
86+
| `flow upgrade` | Update flow-cli |
87+
| `flow learn` | Interactive tutorial |
88+
89+
### AI-Powered
90+
91+
| Command | Description |
92+
| ------------------- | ------------------------- |
93+
| `flow ai <query>` | Ask AI anything |
94+
| `flow do "request"` | Natural language commands |
95+
96+
### Configuration
97+
98+
| Command | Description |
99+
| ------------------ | ------------------ |
100+
| `flow config show` | Show settings |
101+
| `flow config set` | Set a config value |
102+
| `flow plugin` | Manage plugins |
103+
104+
---
105+
106+
## Direct Command Access
107+
108+
Most commands work directly without the `flow` prefix:
109+
110+
```bash
111+
# These are equivalent:
112+
flow work my-project
113+
work my-project
114+
115+
# Direct access commands:
116+
work, pick, dash, finish, hop, why
117+
catch, crumb, inbox, win
118+
timer, morning
119+
doctor, status
120+
```
121+
122+
---
123+
124+
## Examples
125+
126+
### Starting Your Day
127+
128+
```bash
129+
# Morning routine
130+
flow morning
131+
132+
# Or quick version
133+
am
134+
135+
# Start working
136+
flow work my-project
137+
# or just
138+
work my-project
139+
```
140+
141+
### During Work
142+
143+
```bash
144+
# Log wins as you go
145+
flow win "Fixed the auth bug"
146+
147+
# Check progress
148+
flow status
149+
150+
# Take a break
151+
flow break 5
152+
```
153+
154+
### Context-Aware Actions
155+
156+
```bash
157+
# Run tests (auto-detects R/Node/Python)
158+
flow test
159+
160+
# Build project (auto-detects Quarto/npm/R CMD)
161+
flow build
162+
163+
# Preview output
164+
flow preview
165+
```
166+
167+
### Getting Help
168+
169+
```bash
170+
# Search for git-related commands
171+
flow help --search git
172+
173+
# Get help on sync
174+
flow help sync
175+
176+
# List all available commands
177+
flow help --list
178+
```
179+
180+
---
181+
182+
## Dispatchers
183+
184+
Flow-cli includes domain-specific dispatchers that are separate from the `flow` command:
185+
186+
| Dispatcher | Domain | Example |
187+
| ---------- | ----------------- | -------------------- |
188+
| `g` | Git workflows | `g push`, `g status` |
189+
| `r` | R package dev | `r test`, `r check` |
190+
| `qu` | Quarto publishing | `qu preview` |
191+
| `mcp` | MCP servers | `mcp status` |
192+
| `obs` | Obsidian notes | `obs daily` |
193+
| `cc` | Claude Code | `cc`, `cc pick` |
194+
195+
Get help for any dispatcher with `<dispatcher> help`.
196+
197+
---
198+
199+
## Version
200+
201+
```bash
202+
flow version
203+
# flow-cli v4.0.1
204+
```
205+
206+
---
207+
208+
## Tips
209+
210+
!!! tip "Use Direct Commands"
211+
For common commands like `work`, `dash`, `pick`, skip the `flow` prefix for speed.
212+
213+
!!! tip "Search When Unsure"
214+
Use `flow help --search <term>` to find commands you don't remember.
215+
216+
!!! tip "Tab Completion"
217+
If you have completions installed, `flow <Tab>` shows available commands.
218+
219+
---
220+
221+
## Related
222+
223+
- [Command Quick Reference](../reference/COMMAND-QUICK-REFERENCE.md)
224+
- [Dispatcher Reference](../reference/DISPATCHER-REFERENCE.md)
225+
- [Getting Started](../getting-started/quick-start.md)

‎docs/commands/hop.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# hop
2+
3+
> Quick project switch with tmux session management
4+
5+
The `hop` command provides fast project switching, especially powerful when using tmux. It creates or switches to project-specific tmux sessions.
6+
7+
---
8+
9+
## Usage
10+
11+
```bash
12+
hop [project]
13+
```
14+
15+
## Arguments
16+
17+
| Argument | Description | Default |
18+
| --------- | ------------------------- | ------------------------ |
19+
| `project` | Project name to switch to | Interactive picker (fzf) |
20+
21+
---
22+
23+
## What It Does
24+
25+
1. **Without tmux** - Simple `cd` to project directory
26+
2. **With tmux** - Creates or switches to a named tmux session for the project
27+
28+
### Tmux Behavior
29+
30+
When running inside tmux:
31+
32+
- **Session exists** - Switches to the existing session
33+
- **Session doesn't exist** - Creates new session in project directory
34+
- **Session naming** - Uses sanitized project name (replaces special chars with `_`)
35+
36+
---
37+
38+
## Examples
39+
40+
### Basic Switch
41+
42+
```bash
43+
# Switch to a project
44+
hop flow-cli
45+
46+
# Interactive picker (if no project specified)
47+
hop
48+
```
49+
50+
### With Tmux
51+
52+
```bash
53+
# Creates/switches to 'flow_cli' tmux session
54+
hop flow-cli
55+
56+
# View all tmux sessions
57+
tmux list-sessions
58+
```
59+
60+
### Without Tmux
61+
62+
```bash
63+
# Simply changes to project directory
64+
hop my-project
65+
# Changed to: my-project (start tmux for session management)
66+
```
67+
68+
---
69+
70+
## Output
71+
72+
With tmux:
73+
74+
```
75+
✓ Hopped to: flow-cli
76+
```
77+
78+
Without tmux:
79+
80+
```
81+
ℹ Changed to: my-project (start tmux for session management)
82+
```
83+
84+
---
85+
86+
## hop vs work
87+
88+
| Feature | `hop` | `work` |
89+
| ---------------- | ----------------------- | ----------------------- |
90+
| Session tracking | No | Yes (atlas) |
91+
| Editor launch | No | Yes |
92+
| Context display | No | Yes (.STATUS shown) |
93+
| Tmux integration | Full (creates sessions) | No |
94+
| Speed | Instant | Slightly slower (setup) |
95+
| Use case | Quick context switches | Starting focused work |
96+
97+
**Rule of thumb:**
98+
99+
- Use `work` when starting a focused work block
100+
- Use `hop` when quickly checking something in another project
101+
102+
---
103+
104+
## Tmux Tips
105+
106+
!!! tip "View All Sessions"
107+
```bash # List all tmux sessions
108+
tmux ls
109+
110+
# Kill a specific session
111+
tmux kill-session -t session_name
112+
```
113+
114+
!!! tip "Detach and Return"
115+
`bash
116+
# Detach from current session: Ctrl-b d
117+
# Then hop to another project
118+
hop other-project
119+
`
120+
121+
---
122+
123+
## Related Commands
124+
125+
| Command | Description |
126+
| ----------------- | ----------------------------------- |
127+
| [`work`](work.md) | Start focused session (with editor) |
128+
| [`pick`](pick.md) | Interactive project picker |
129+
| [`dash`](dash.md) | View all projects dashboard |
130+
131+
---
132+
133+
## See Also
134+
135+
- [`work`](work.md) - Start a full work session
136+
- [`pick`](pick.md) - Interactive project picker
137+
- [Workflow Quick Reference](../reference/WORKFLOW-QUICK-REFERENCE.md)

0 commit comments

Comments
 (0)