Complete Guide to getctx

Everything you need to know about using getctx to aggregate code context for AI tools.

Table of Contents

1. Overview2. Keyboard Shortcuts3. Usage Guide4. Configuration5. Troubleshooting

Overview

getctx (Get Context) is a CLI tool written in Go that allows you to interactively select files and folders from your filesystem and concatenate their contents into a single output file. The primary use case is aggregating source code context for AI coding assistants, LLMs, bug reports, or documentation.

Key Benefits

  • • Quickly gather relevant code files for AI context
  • • Interactive TUI built with bubbletea framework
  • • Intelligent file exclusion (node_modules, .git, binaries)
  • • Real-time filtering and search capabilities
  • • Structured logging for debugging

Keyboard Shortcuts

Navigation

Move cursor up/down↑ / ↓
Enter directoryEnter
Go to parent directoryBackspace

Selection

Toggle file selectionSpace
Select all visible itemsCTRL+A

Filtering & Search

Activate filter mode/
Direct path inputCTRL+P
Clear filter / Cancel inputEsc

Program Control

Save and exitq
Abort and exit immediately (in normal mode). Cancels input or filtering if active.CTRL+C

Usage Guide

Basic Workflow

  1. 1.
    Launch the tool - Run getctx in your project directory
  2. 2.
    Navigate - Use arrow keys to browse files and folders
  3. 3.
    Select - Press Space to select individual files or CTRL+A for bulk selection
  4. 4.
    Filter (optional) - Press / to search for specific files
  5. 5.
    Save - Press q to generate the context file

Advanced Features

Direct Path Input

Press CTRL+P to type or paste paths directly. This is useful when you know exactly where you want to go.

  • • Supports tab-completion
  • • Use ~ for home directory
  • • Works with both absolute and relative paths

Real-Time Filtering

Press / to activate filter mode and search through files instantly.

  • • Case-insensitive matching
  • • Instant in-memory filtering
  • • Navigate and select from filtered results
  • • Press Esc to clear the filter

Custom Output File

Specify a custom output file with the -o flag:

getctx -o ai-context.txt

Configuration

Exclusion Lists

getctx automatically excludes common directories and files. The exclusion lists are defined in internal/config/config.go:

Excluded Folders

node_modules, .git, .vscode, dist, build, target, vendor

Excluded Files

.DS_Store, Thumbs.db, package-lock.json, yarn.lock

Excluded Extensions

.png, .jpg, .gif, .pdf, .zip, .exe, .dll, .so

Troubleshooting

Command not found

Ensure $GOPATH/bin is in your PATH:

export PATH=$PATH:$(go env GOPATH)/bin

Enable debug logging

Run with the --debug flag to generate debug.log:

getctx --debug

UI rendering issues

Ensure your terminal supports ANSI colors and has sufficient dimensions. Minimum recommended size is 80x24.

Need More Help?

Check out the GitHub repository for issues, discussions, and contributions.

View on GitHub