Interactive mode

When you run a search without --no-interactive (and outside a CI environment), github-code-search launches a full-screen TUI. This is the main advantage of the tool over GitHub's web search: results are grouped by repository, and you can fold, navigate, filter, and select exactly what you need.

Launching the TUI

bash

github-code-search "useFeatureFlag" --org fulll

TUI overview

text

 github-code-search  useFeatureFlag in fulll
3 repos · 4 files
← / → fold/unfold  ↑ / ↓ navigate  spc select  a all  n none  f filter  h help  ↵ confirm  q quit

▸   fulll/service-b                                         3 matches
▾ ✓ fulll/service-a                                       2 matches
      ✓ src/middlewares/featureFlags.ts
            …const flag = useFeatureFlag('new-onboarding'); if (!flag) return next();…
      ✓ tests/unit/featureFlags.test.ts
            …expect(useFeatureFlag('new-onboarding')).toBe(true);…
▸   fulll/legacy-app                                     1 match

▸ — folded repo (extracts hidden)
▾ — unfolded repo (extracts visible)
✓ — selected (green in the terminal)
— deselected (space — keeps columns aligned)
Match counts are right-aligned to the terminal width
The header badge github-code-search is displayed on a violet background

Keyboard shortcuts

Key	Action
`↑` / `↓`	Navigate between repos and extracts
`←`	Fold the repo under the cursor
`→`	Unfold the repo under the cursor
`Space`	Select / deselect the current repo or extract
`a`	Select all — on a repo row: all repos and extracts; on an extract row: all extracts in that repo. Respects any active filter.
`n`	Select none — same context rules as `a`. Respects any active filter.
`f`	Open the filter bar — type to narrow visible repos or files
`t`	Cycle the filter target: `path` → `content` → `repo` → `path`. When on a picked repo (marked `◈`, `--group-by-team-prefix` active): enter re-pick mode instead.
`r`	Reset the active filter and show all repos / extracts
`h` / `?`	Toggle the help overlay
`Enter`	Confirm and print selected results (also closes the help overlay)
`q` / `Ctrl+C`	Quit without printing

Mouse support

The TUI supports mouse interaction via the terminal's SGR mouse protocol. You can navigate, select, and fold repos using your mouse alongside keyboard shortcuts.

Scrolling

Scroll wheel (up/down) — move the viewport up or down by 3 rows.
Momentum scrolling (trackpad): clicks are ignored during and immediately after the scroll gesture to prevent accidental selections while the scroll is still decelerating.

Single-click

Single-click on any row — move the cursor to that row (equivalent to ↑/↓ navigation).

Double-click

Double-click actions depend on both the row type (repo or extract) and the click zone (columns 1–3 vs. columns 4+):

On a repo row (▸ ✓ repo-name):

Click zone	Action
Fold control (columns 1–2)	Toggle fold (`←` / `→`)
Checkbox or content (columns 4+)	Toggle repo selection (`Space`)

On an extract row ( ✓ path:line:col):

Click zone	Action
Content area (columns 4+)	Toggle extract selection
Navigation-only zone (columns 1–3)	No action (single-click only)

The checkbox zone (column 4 and beyond) is full-width for selection, so you can double-click anywhere on the row content to toggle selection.

Accessibility note

Mouse support is optional; all features are fully accessible via keyboard. Many users prefer the keyboard-only workflow for speed and precision during large searches.

Selection behaviour

Selecting a repo row (Space) cascades to all its extracts.
Deselecting a repo row deselects all its extracts.
Selecting an individual extract keeps the parent repo selected as long as at least one extract is selected.
Deselecting the last extract in a repo automatically deselects the repo too.

Filter mode

Press f to enter filter mode. A two-line bar appears at the top of the results:

text

🔍 [path]  src/▌                            3 repos · 5 files
          ←→ move  ·  ⌥←→ word  ·  ⌥⌫ del word  ·  Tab regex  ·  Shift+Tab target  ·  ↵ OK  ·  Esc cancel

Line 1: the filter input field with a text cursor (▌), plus live stats on the right (how many repos and files are currently visible).
Line 2: available shortcuts, indented to align with the input text.

Filter targets

Press t (outside filter mode) or Shift+Tab (inside filter mode) to cycle through three matching modes:

Badge	Target	What is matched	Unit shown/hidden
`[path]`	`path`	File path — default, case-insensitive substring	Individual file
`[content]`	`content`	Code fragment text returned by GitHub Search	Individual file
`[repo]`	`repo`	Full repository name (`org/repo`), case-insensitive	Entire repo

The matching part is highlighted in yellow in the result list so you can instantly see why a row is visible.

Regex mode

Press Tab in filter mode to toggle regular-expression matching. The badge updates to [path·regex] (or [content·regex], etc.) while regex is active. If the expression is invalid, it matches nothing (no results are shown until you correct the pattern).

Confirmed filter

After pressing Enter the filter is locked and the bar shows a compact summary:

text

🔍 [repo]  billing  3 matches in 1 repo shown · 2 hidden in 2 repos  r to reset

Press r at any time to clear the filter and show all results again.

INFO

a (select all) and n (select none) always operate only on the currently visible repos and extracts when a filter is active. The filter target is taken into account: with filterTarget=repo only repos whose name matches are affected.

Full workflow example

1 — Run the search:

bash

github-code-search "useFeatureFlag" --org fulll

2 — Navigate with ↑/↓, unfold repos with →.

3 — Filter to src/ files only:

Press f, type src/, press Enter.

4 — Select all visible extracts:

Press a on a repo row to select all its visible extracts.

5 — Deselect a specific extract:

Navigate to it with ↑/↓, press Space.

6 — Confirm:

Press Enter. The selected results are printed to stdout, along with a replay command.

Output and replay command

After pressing Enter:

text

2 repos · 2 files selected

- **fulll/service-a** (1 match)
  - [ ] [src/middlewares/featureFlags.ts:2:19](https://github.com/fulll/service-a/blob/main/src/middlewares/featureFlags.ts#L2)
- **fulll/service-b** (1 match)
  - [ ] [src/flags.ts:3:14](https://github.com/fulll/service-b/blob/main/src/flags.ts#L3)

replay command

bash

github-code-search "useFeatureFlag" --org fulll --no-interactive \
  --exclude-repositories legacy-app

The replay command encodes your exact selection (exclusions) so you can reproduce the result in CI without the UI. See Non-interactive mode for more.

Output format

By default output is Markdown. Pass --format json to get a JSON payload instead:

bash

github-code-search "useFeatureFlag" --org fulll --format json

See Output formats for the full reference.

Interactive mode ​

Launching the TUI ​

TUI overview ​

Keyboard shortcuts ​

Mouse support ​

Scrolling ​

Single-click ​

Double-click ​

Accessibility note ​

Selection behaviour ​

Filter mode ​

Filter targets ​

Regex mode ​

Confirmed filter ​

Full workflow example ​

Output and replay command ​

Output format ​

Interactive mode

Launching the TUI

TUI overview

Keyboard shortcuts

Mouse support

Scrolling

Single-click

Double-click

Accessibility note

Selection behaviour

Filter mode

Filter targets

Regex mode

Confirmed filter

Full workflow example

Output and replay command

Output format