ctx

README

ctx

ctx helps you explore a project from the terminal. List directory trees, read source files with optional embedded documentation, analyse call chains, or fetch documentation straight from GitHub—all with a single CLI.

Highlights

• One command for project discovery. Inspect structure, source, and dependencies without leaving the shell.
• Human-friendly or machine-ready output. Toon (default), raw text, JSON, and XML renderers share the same data.
• Clipboard and automation built in. Copy results, run in MCP server mode, or integrate with scripts.
• Optional documentation enrichment. Embed local symbol docs or pull curated GitHub documentation alongside output.
• Automated dependency documentation. ctx doc discover scans Go/npm/Python dependencies, fetches their upstream docs, and writes curated bundles to docs/dependencies.

Quick Start

Install and try the core workflows:

1. Install the latest release:

   go install github.com/tyemirov/ctx@latest
   

2. Explore a directory tree (Toon format by default):

   ctx tree .
   

3. Review file content with documentation:

   ctx content main.go --doc
   

4. Analyse a call chain:

   ctx callchain github.com/tyemirov/ctx/internal/commands.GetContentData
   

Need binaries instead? Grab pre-built releases for macOS, Linux, and Windows from the Releases page.

Installation

1. Install Go ≥ 1.21.
2. Add $GOBIN (or $GOPATH/bin) to your PATH.
3. Run go install github.com/tyemirov/ctx@latest.
4. Verify with ctx --help.

Core Workflows

Explore project layout

Surface a tree for one or more paths. Toon is the default; switch formats when needed.

ctx tree repoA repoB --format raw

• -e/--e excludes directories by name during traversal.
• --summary (on by default) appends totals; disable with --summary false.

Inspect files with context

Mix files and directories, embed documentation, and optionally copy results.

ctx content cmd/internal --doc --copy

Analyse call chains

Trace callers and callees across Go, Python, and JavaScript.

ctx callchain fmt.Println --depth 2 --format json

Fetch GitHub documentation

Render docs stored in remote repositories:

ctx doc --path example/project/docs --doc full

Provide repository coordinates (owner/repo[/path]) or a GitHub URL. Combine --ref, --rules, and clipboard flags as needed. Use --doc relevant to limit output to referenced symbols or --doc full to include entire documentation bundles.

Generate dependency documentation

Trace the dependencies used in your project and hydrate a local docs/dependencies tree (one Markdown file per package):

ctx doc discover . --output-dir docs/dependencies

• Supports Go modules (go.mod), npm (package.json), and Python (requirements*.txt, pyproject.toml) at once.
• Toggle ecosystems with --ecosystems go,js,python, include dev tooling via --include-dev, and capture indirect Go modules with --include-indirect.
• Emit machine-readable manifests for automation with --format json.

Remote documentation calls support anonymous access for public repositories. Export GH_TOKEN, GITHUB_TOKEN, or GITHUB_API_TOKEN to authenticate when working with private sources or to raise rate limits. When targeting a custom API base (for example, a mock server in tests), any placeholder token value is sufficient.

Helpful Flags at a Glance

ctx <tree|t|content|c|callchain|cc|doc> [arguments] [flags]

Flag	Commands	What it does
-e, --e <pattern>	tree, content	Skip matching child directories during traversal (repeatable).
--no-gitignore, --no-ignore	tree, content	Disable loading of .gitignore/.ignore.
--git	tree, content	Include the .git directory.
`--format <toon	raw	json
--summary <bool>	tree, content	Toggle aggregate totals (on by default).
--tokens	tree, content	Estimate tokens (see Architecture for backend details).
--model <name>	tree, content	Choose the tokenizer model.
`--doc <disabled	relevant	full>`
--docs-attempt	content, callchain	Try to fetch GitHub docs for imported modules.
--depth <number>	callchain	Limit traversal depth (default 1).
--copy, --c	tree, content, callchain, doc	Copy output to the clipboard after rendering.
--copy-only, --co	tree, content, callchain, doc	Copy without printing to stdout.
--mcp	root	Run an MCP server with JSON endpoints.

Boolean flags accept true/false, yes/no, on/off, or 1/0. Combine configuration defaults in config.yaml with flag overrides to tailor each command.

Clipboard and Copy-Only Workflows

• --copy mirrors terminal output to your system clipboard.
• --copy-only suppresses stdout while still copying, which keeps logs clean in scripted environments.
• Persist clipboard defaults by setting copy: true or copy_only: true under the relevant command in config.yaml.

If the current platform does not support clipboard access, commands fail fast with a descriptive error so you can fall back to piping output.

MCP Integration

Run ctx --mcp to expose commands over HTTP. The server:

• Binds to an ephemeral loopback address and prints the endpoint.
• Serves /capabilities (command list), /environment (working directory), and /commands/<name> (execution).
• Always returns JSON mirroring CLI output, so automation can rely on a single schema.

Use it with agents such as Claude Desktop or the Codex CLI. See ARCHITECTURE.md for configuration snippets and advanced guidance.

Configuration and Ignore Rules

• .ignore and .gitignore files are respected at every directory root during traversal.
• Explicit file arguments are never filtered.
• Use the repeatable -e/--e flag to skip direct child directories by name.
• Create config.yaml to store per-command defaults (format, documentation mode, summary, clipboard, etc.).

Token Counting and Binary Files

• Add --tokens to tree or content commands to track token estimates alongside file counts and sizes.
• Choose alternative models with --model <name>; details on supported backends live in ARCHITECTURE.md.
• Raw output omits binary payloads by default. Add a [binary] section to .ignore to include base64 content in JSON and XML outputs.

Examples

Display a raw tree view excluding dist folders:

ctx tree projectA projectB -e dist --format raw

Copy Toon output without printing to stdout:

ctx content pkg --doc --copy-only

Analyse a call chain in XML with embedded docs:

ctx callchain github.com/tyemirov/ctx/internal/commands.GetContentData --depth 2 --doc --format xml

Need More Detail?

• ARCHITECTURE.md explains internal design, streaming, token backends, MCP wiring, and release steps.
• POLICY.md documents confident-programming rules for contributors.
• PRD.md captures product requirements and behaviour expectations.
• CHANGELOG.md lists release history and pending changes.

License

ctx is released under the MIT License.