terminal interactive segmentation

terminal interactive segmentation.md

Here's how the terminal-only flow would work, following patterns similar to git add -p and git rebase -i:[1][2]

Initial Invocation

$ git add .
$ omni --segment

Interactive Terminal Flow

Step 1: Initial Analysis Screen

Analyzing changes... Done!
Found 10 modified files. Suggested 3 commits.

┌─────────────────────────────────────────────────────────┐
│ Commit Segmentation (3 commits from 10 files)          │
└─────────────────────────────────────────────────────────┘

  1. [✓] refactor: authentication system (4 files)
  2. [ ] feat: API v2 endpoints (3 files)  
  3. [ ] test: auth coverage and docs (3 files)

Commands: [n]ext [p]rev [e]dit [s]plit [m]erge [v]iew [a]ccept [q]uit
Current: 1/3
>

Step 2: Navigation with Single-Key Commands

> e     # Edit commit 1

┌─────────────────────────────────────────────────────────┐
│ Edit Commit 1/3                                         │
└─────────────────────────────────────────────────────────┘

Title: refactor: authentication system

Message (press 'i' to edit, Esc to return):
Move JWT logic to dedicated auth service

- Extract token generation and validation to AuthService
- Add refresh token rotation mechanism  
- Implement proper error handling for expired tokens
- Update security headers and CORS configuration

Files (4):
  • src/services/AuthService.ts
  • src/middleware/authenticate.ts
  • src/utils/jwt.ts
  • src/config/security.ts

[i] Edit  [f] Move files  [Enter] Save  [Esc] Cancel

Step 3: Multi-Select for Merging

> m     # Enter merge mode

┌─────────────────────────────────────────────────────────┐
│ Merge Mode (Space to select, Enter to merge)           │
└─────────────────────────────────────────────────────────┘

  [✓] 1. refactor: authentication system (4 files)
  [✓] 2. feat: API v2 endpoints (3 files)  
  [ ] 3. test: auth coverage and docs (3 files)

Selected: 2 commits (7 files total)
Press Enter to merge, Esc to cancel
>

Step 4: Split Flow[2]

> s     # Split commit 2

┌─────────────────────────────────────────────────────────┐
│ Split: feat: API v2 endpoints (3 files)                │
└─────────────────────────────────────────────────────────┘

Select files for FIRST commit (Space to toggle, Enter when done):

  [✓] src/api/routes/users.ts
  [✓] src/api/routes/profile.ts  
  [ ] src/middleware/apiVersion.ts

Remaining files will go to second commit.
>

Step 5: Quick View Mode

> v     # View all commits summary

┌─────────────────────────────────────────────────────────┐
│ Commit Summary                                          │
└─────────────────────────────────────────────────────────┘

Commit 1: refactor: authentication system
  4 files | 156 additions, 89 deletions

Commit 2: feat: API v2 endpoints  
  3 files | 234 additions, 12 deletions

Commit 3: test: auth coverage and docs
  3 files | 445 additions, 0 deletions

Total: 835 additions, 101 deletions across 10 files

[Enter] Return  [a] Accept all  [q] Quit

Step 6: Final Acceptance

> a     # Accept and create commits

Creating commits...
✓ Created: refactor: authentication system (8a3f2d1)
✓ Created: feat: API v2 endpoints (9bc4e8a)  
✓ Created: test: auth coverage and docs (7f1a5c2)

Done! 3 commits created.

Alternative: Stream-Based Flow (No TUI)[3]

For scriptability and simpler terminals, a more traditional prompt-based approach:

$ omni --segment

Commit 1/3: refactor: authentication system (4 files)
Edit title? [y/N]: n
Edit message? [y/N]: y
<opens $EDITOR>
Include in final commits? [Y/n]: y

Commit 2/3: feat: API v2 endpoints (3 files)  
Edit title? [y/N]: n
Edit message? [y/N]: n
Include in final commits? [Y/n]: y

Commit 3/3: test: auth coverage and docs (3 files)
Edit title? [y/N]: n  
Edit message? [y/N]: n
Include in final commits? [Y/n]: y

Summary:
  3 commits will be created
  10 files across all commits
  
Proceed? [Y/n]: y
✓ Done!

Key Terminal UX Patterns Used[4][5]

Single-character commands - Like git add -p with y/n/s/q responses, keeping interactions fast[2]

Editor integration - Opening $EDITOR for longer text like commit messages, following Unix conventions[3]

Visual selection states - Using [✓] and [ ] for checkbox states, > for current position

Escape hatches - Always providing q to quit, Esc to cancel, consistent with vim/less patterns[6]

Status indicators - Progress like "1/3", file counts, and what's currently selected

Command bar - Persistent reminder of available commands at bottom, similar to nano or htop[7]

The TUI approach uses libraries like ncurses or modern alternatives (bubbletea for Go, blessed for Node) to handle cursor positioning and screen updates without full redraws. The simpler prompt-based flow works in any terminal and remains scriptable.[8][5][6][3]

1 2 3 4 5 6 7 8 9 10

A fully-terminal version would feel like a mix of git add -p (interactive review/splitting) and a fuzzy multi-select picker like fzf (select many with Tab/Shift-Tab), plus an editor step for commit messages.[1][2][3]

Option A: Full-screen TUI (still terminal)

This is a “curses”/TUI screen inside the terminal (no separate macOS window), where the left list, preview, and editor are just panes.[4][3]

Flow (example transcript):

acme-web % git add .
acme-web % omni segment
# omni scans staged diff and suggests 3 segments

┌ omni --segment ───────────────────────────────────────────────────────────────┐
│ Segments (TAB multi-select)             Preview / Message                     │
│                                                                              │
│ [x] SEG-01 refactor(auth): extract S...   Title: refactor(auth): extract ...  │
│ [ ] SEG-02 feat(auth): enforce rotat...   Body:                               │
│ [ ] SEG-03 chore: run formatter, fix...   - Why: ...                          │
│                                                                              │
│ Files (for active):                                                           │
│  - src/server/routes/auth.ts                                                   │
│  - src/server/services/session-manager.ts                                      │
│  ...                                                                           │
│                                                                              │
│ Keys: j/k move · TAB select · m merge · s split · e edit · enter accept · esc cancel │
└──────────────────────────────────────────────────────────────────────────────┘

Key interactions:

• Multi-select segments: use TAB / SHIFT+TAB style bindings (common in fzf --multi).[2][3]
• Merge: select 2+ segments, press m → tool asks for the merged commit title/body (or opens editor).[5]
• Split: select exactly 1 segment, press s → tool asks how to split (by file, by hunk, or by “suggested split”).[1]
• Edit message: press e to edit title/body in an inline editor or by launching $EDITOR (like Git does for commit messages).[6]
• Accept/cancel: Enter to apply (creates commits), Esc (or q) to abort (like quitting interactive flows).[7]

Option B: Pure prompt-by-prompt (no full-screen UI)

This version never “draws a screen”; it’s just sequential prompts, similar in spirit to patch mode asking y/n/s decisions.[7][1]

Flow (example):

acme-web % git add .
acme-web % omni segment

Proposed segments:
  1) refactor(auth): extract SessionManager + move token logic   (6 files)
  2) feat(auth): enforce rotation + add integration tests        (3 files)
  3) chore: run formatter, fix lint, update imports             (1 file)

Select segments (e.g. 1 3, or 'all'): 1 2 3
Action? [enter=continue, m=merge, s=split, v=view files, d=diff, q=cancel]: v 2
Files in segment 2:
  - src/server/services/session-manager.ts
  - src/server/middleware/auth.ts
  - test/integration/auth-refresh.test.ts

Action? ...: s 2
Split segment 2 by: [1=file groups, 2=hunks, 3=suggested] 3
Created segments:
  2a) feat(auth): enforce rotation
  2b) test(auth): add refresh-token reuse coverage

Edit messages now? [Y/n]: Y
Editing "2a" (opens $EDITOR)...

Ready to commit 4 commits. Proceed? [Y/n]: Y
✔ git commit -m "refactor(auth): extract SessionManager..." ...
✔ git commit -m "feat(auth): enforce rotation" ...
✔ git commit -m "test(auth): add refresh-token..." ...
✔ git commit -m "chore: run formatter..." ...

How “split” works in terminal

Splitting can mirror what git add -p does: “split this hunk” vs “stage this hunk”, except your tool is splitting staged changes into commit buckets instead of staging hunks. In a prompt-only version, the split step is typically: choose a segment → choose split mode → confirm the resulting two new segment titles.[7][1]

How “merge” works in terminal

Merging is just “combine selected buckets”, then edit one combined commit message. In a TUI, “merge” would be a single keystroke (m) on a multi-selection, which is exactly the kind of interaction multi-select TUIs support.[3][5]

Which version are you aiming for in practice: a full-screen terminal TUI (fzf/bubbletea-like), or a simple prompt-by-prompt flow that works even over very minimal SSH terminals?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21