You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(readme): update command reference and UI styling
- Document newly integrated CLI commands: `web`, `diff`, and `release-context`.
- Remove references to the deprecated `ast` command and its `ast-grep` dependency.
- Update architecture documentation to reflect the inclusion of DOM parsing libraries (`beautifulsoup4`, `markdownify`) instead of `nbformat`.
- Refactor header badges and contact sections using centered shields.io SVGs for a cleaner layout.
**CLI utilities for AI-assisted development context and workflow automation.**
11
7
12
-
Gathering context for an LLM (whether ChatGPT, Claude, or Gemini) usually means copying and pasting multiple files, scraping git diffs, and manually formatting terminal outputs. Focal automates this boilerplate repository extraction so you can stay in flow and feed your AI assistant exactly what it needs to understand your codebase.
Gathering context for an LLM (whether ChatGPT, Claude, or Gemini) usually means copying and pasting multiple files, scraping git diffs, and manually formatting terminal outputs. Focal automates this boilerplate repository extraction so you can stay in flow and feed your AI assistant exactly what it needs to understand your codebase or external documentation.
*See [Detailed Installation & Autocompletion](#-detailed-installation--autocompletion) below for building from source and configuring Zsh/Bash.*
23
29
24
-
-----
30
+
---
25
31
26
32
## 💡 Design Philosophy
27
33
28
34
Focal is built to maximize LLM attention window efficiency and stay out of your way. It adheres to a strict pipeline-native architecture to avoid generating bloated, noisy context blocks:
29
35
30
-
1.**High Signal, Low Noise:** When generating branch topologies or diffs, Focal aggressively filters out binary blobs, lockfiles, and minified assetsusing strict heuristic sets. It reserves token bandwidth for the source code that actually matters.
36
+
1.**High Signal, Low Noise:** When generating branch topologies or diffs, Focal aggressively filters out binary blobs, lockfiles, minified assets, and DOM noise using strict heuristic sets. It reserves token bandwidth for the source code and semantic text that actually matters.
31
37
32
38
1.**Clipboard-First Execution:** Outputs are automatically calculated for token length and piped directly to your system's native clipboard manager (`pbcopy`, `wl-copy`, `xclip`, or `xsel`). No intermediate files; just run the command and paste.
33
39
34
-
1.**Pipeline Native:** Core routing and file manipulation are handled by ultra-fast UNIX utilities (`rg`, `fd`, `fzf`, `bat`). Python is strictly reserved as an asynchronous backend to handle complex data transformations, like parsing Jupyter Notebook ASTs or resolving Git commit topologies.
40
+
1.**Pipeline Native:** Core routing and file manipulation are handled by ultra-fast UNIX utilities (`rg`, `fd`, `fzf`, `bat`). Python is strictly reserved as an asynchronous backend to handle complex data transformations, like parsing Jupyter Notebook ASTs, resolving Git commit topologies, or stripping HTML structure.
35
41
36
-
1.**Clear Formatting:** LLMs need structural boundaries. Files, diffs, GitHub API responses, and CI logs are automatically wrapped in LLM-optimized Markdown blocks, ensuring the model understands file paths, language semantics, and context hierarchies.
42
+
1.**Clear Formatting:** LLMs need structural boundaries. Files, diffs, GitHub API responses, web pages, and CI logs are automatically wrapped in LLM-optimized Markdown blocks, ensuring the model understands file paths, language semantics, and context hierarchies.
37
43
38
-
1.**Fail Loud, Fail Early:** Pre-flight checks (`require_cmd`) ensure all system dependencies are present before any context generation is attempted. If a required binary is missing, Focal aborts cleanly.
44
+
1.**Fail Loud, Fail Early:** Pre-flight checks ensure all system dependencies are present before any context generation is attempted. If a required binary is missing, Focal aborts cleanly.
39
45
40
-
-----
46
+
---
41
47
42
48
## ⚡️ Performance & Latency Isolation
43
49
44
50
Focal is built to be lightweight, utilizing bash wrappers to defer Python's startup overhead until strictly necessary.
45
51
46
52
1.**Fast-Path Execution:** Commands like `focal search`, `focal file`, or `focal tree` execute entirely via compiled binaries like `ripgrep` or `tree`/`fd`, meaning time-to-clipboard is measured in milliseconds.
47
53
48
-
1.**Heavy-Path Execution:** For complex extractions like `focal wip-context` or `focal ci-fail`, the bash layer dynamically resolves a localized `uv` virtual environment to execute the Python backend, ensuring global namespace isolation without sacrificing execution speed.
54
+
1.**Heavy-Path Execution:** For complex extractions like `focal wip-context`, `focal web`, or `focal ci-fail`, the bash layer dynamically resolves a localized `uv` virtual environment to execute the Python backend, ensuring global namespace isolation without sacrificing execution speed.
49
55
50
56
Our CI pipeline enforces strict linting and type-checking across both the Python (`ruff`, `mypy`, `pytest`) and Shell (`shellcheck`, `shfmt`, `bats`) stacks to guarantee architectural stability.
51
57
52
-
-----
58
+
---
53
59
54
60
## 📦 Detailed Installation & Autocompletion
55
61
@@ -65,7 +71,7 @@ just install
65
71
66
72
*Note: The `just install` pipeline resolves a localized Python environment and symlinks the entrypoint binary into `~/.local/bin`. Ensure this directory is prioritized in your system `$PATH`.*
67
73
68
-
-----
74
+
---
69
75
70
76
### Shell Autocompletion
71
77
@@ -96,25 +102,17 @@ compinit
96
102
97
103
#### 2. Bash
98
104
99
-
To enable Bash completions, you need to source the included `focal.bash` script.
100
-
101
-
**If installed via Homebrew:**
102
-
103
-
Homebrew routes the completion file automatically. Ensure you have `bash-completion` installed and configured in your profile.
104
-
105
-
**If installed from source:**
106
-
107
-
Point directly to the completion file in your `~/.bashrc` or `~/.bash_profile`:
105
+
To enable Bash completions, you need to source the included `focal.bash` script. Point directly to the completion file in your `~/.bashrc` or `~/.bash_profile`:
108
106
109
107
```bash
110
108
source~/.local/share/focal/completions/focal.bash # Adjust path if cloned elsewhere
111
109
```
112
110
113
-
-----
111
+
---
114
112
115
113
## 🚀 Usage
116
114
117
-
Focal is designed to be run from anywhere inside a valid Git workspace.
115
+
Focal is designed to be run from anywhere inside a valid Git workspace, but also handles external URLs and clipboard streams.
118
116
119
117
### Basic Context Gathering
120
118
@@ -128,49 +126,75 @@ focal file
128
126
focal files
129
127
```
130
128
131
-
### Advanced Git & GitHub Context
129
+
### Git & Working Tree
132
130
133
131
To grab the exact state of your current feature branch (uncommitted changes, commit topology, microscopic diffs) compared to `main`:
134
132
135
133
```bash
136
134
focal wip-context
137
135
```
138
136
137
+
To quickly grab the diff of your currently staged or uncommitted files:
138
+
139
+
```bash
140
+
focal diff --staged
141
+
```
142
+
143
+
### Web & Documentation Context
144
+
145
+
You can pipe a library's documentation page directly to your clipboard, stripped of all DOM noise (navbars, scripts, footers):
146
+
147
+
```bash
148
+
# Fetch from a public URL
149
+
focal web https://docs.python.org/3/
150
+
151
+
# Parse an authenticated dashboard copied to your clipboard
152
+
pbpaste | focal web
153
+
```
154
+
155
+
### GitHub API Context
156
+
139
157
Need to debug why your GitHub Actions pipeline crashed? Grab the error logs and metadata instantly:
140
158
141
159
```bash
142
160
focal ci-fail
143
161
```
144
162
145
-
*Result: Focal fetches the failed run via `gh`, formats the raw logs into an LLM-friendly markdown block, calculates the token estimate, and copies it to your clipboard.*
163
+
To aggregate a release context by compiling all pull request intents merged since the last Git tag:
164
+
165
+
```bash
166
+
focal release-context
167
+
```
146
168
147
-
-----
169
+
---
148
170
149
171
## 🛠 Command Reference
150
172
151
-
### Local Context Gathering
173
+
### Local & Web Context Gathering
152
174
153
175
| Command | Description |
154
-
|:--- |:--- |
176
+
| --- | --- |
155
177
|`focal file`| Interactively selects a single file and copies its formatted contents. |
156
178
|`focal files`| Interactively (or via glob) selects multiple files and copies contents + metadata. |
|`focal tree`| Generates and copies the repository directory tree, ignoring `.git` and build caches. |
159
181
|`focal api`| Extracts an overview of Python classes and functions using `ripgrep`. |
160
182
|`focal search`| Searches the codebase for a regex pattern and copies the results with surrounding context. |
161
183
|`focal symbol`| Locates files containing a specific symbol and copies their full contents. |
162
-
|`focal ast`|Searches the codebase using an abstract syntax tree pattern (requires `ast-grep`). |
184
+
|`focal web`|Extracts semantic markdown from public URLs or piped HTML, stripping DOM noise. |
163
185
164
186
### Git & GitHub Extraction
165
187
166
188
| Command | Description |
167
-
|:--- |:--- |
189
+
| --- | --- |
168
190
|`focal wip-context`| Extracts a comprehensive diff, uncommitted status, and topological context for your active branch. |
191
+
|`focal diff`| Copies a formatted git diff of uncommitted or staged (`--staged`) changes. |
169
192
|`focal pr-diff`| Fetches metadata, description intent, and the full code diff for a GitHub Pull Request. |
170
193
|`focal issue-graph`| Copies a GitHub issue description alongside its sequential comment thread. |
194
+
|`focal release-context`| Copies metadata and intent for all PRs merged since the last release tag. |
171
195
|`focal ci-fail`| Fetches and formats GitHub Actions CI failure logs for debugging. |
172
196
173
-
-----
197
+
---
174
198
175
199
## ⚙️ Dependencies & Toolchain
176
200
@@ -180,16 +204,15 @@ Focal orchestrates several industry-standard CLI tools to achieve low-latency ex
180
204
-**`fd`**: Required for high-speed file traversal (respects `.gitignore`).
181
205
-**`bat`**: Required for syntax-highlighted TUI previews.
182
206
-**`rg` (ripgrep)**: Required for the `search`, `api`, and `symbol` regex extractors.
183
-
-**`gh` (GitHub CLI)**: Required for `pr-diff`, `issue-graph`, and `ci-fail`.
184
-
-**`ast-grep`**: Required for semantic AST searching (`focal ast`).
207
+
-**`gh` (GitHub CLI)**: Required for `pr-diff`, `issue-graph`, `ci-fail`, and `release-context`.
185
208
186
-
-----
209
+
---
187
210
188
211
## 🤝 Collaboration
189
212
190
213
This repository utilizes a dual-language testing and linting architecture.
191
214
192
-
-**Python:** 100% type-hinted via `mypy`, formatted with `ruff`, and tested with `pytest`. Notebook parsing uses `nbformat` to safely construct ASTs.
215
+
-**Python:** 100% type-hinted via `mypy`, formatted with `ruff`, and tested with `pytest`. Parsing pipelines utilize `beautifulsoup4` and `markdownify` for AST and DOM manipulation.
193
216
-**Bash:** Strictly linted via `shellcheck`, formatted with `shfmt`, and behaviorally tested using the `bats` framework.
194
217
195
218
To run the complete local CI pipeline before submitting a pull request:
@@ -200,15 +223,15 @@ just ci
200
223
201
224
Please feel free to open an issue or PR if you'd like to see a specific context extractor added to the suite.
0 commit comments