Quick start • How it works • Commands • Safety • Validation • Security • 한국어
In a closed network or internal development environment, an external AI assistant cannot access the repository directly. Developers must prepare the relevant code and project context separately.
siloBrief is a local CLI that turns approved Python project context into a Markdown brief. You choose the information and source excerpts before writing the file. The result is input for another tool, not a generated code change.
- License: Apache License 2.0
- Platforms: Windows and Ubuntu
- Python: 3.10 and newer
- Runtime dependency:
prompt-toolkit
for interactive file and function completion - Network access: none
If you use WSL, keep the project in the WSL Linux filesystem. For a project under /mnt/c
or
another Windows-mounted path, run sb
from native Windows. sb setup
stops if the mount cannot create state files without overwriting an existing entry.
Install the stable package from PyPI and verify the command:
python -m pip install silobrief
sb --version
Expected output:
siloBrief 1.2.1
Create a practice project:
sb example ./silobrief-practice
cd silobrief-practice
The generated project is a minimal Flask signup/login API backed by SQLite. JWT creation and
verification helpers live in private/jwt.py
, while the local signing key is stored in the
gitignored .env
file. The login route does not use them yet.
Start the first task from the same directory:
sb setup .
sb language --cli en --brief en
sb ignore private --as "JWT settings"
sb init
sb log app.py --comment "Use private.jwt.create_access_token(user_id, username) to issue a JWT."
sb search "successful login response"
sb brief
At Task
, enter:
Add PyJWT to requirements.txt. On successful login, return an access_token that expires after one
hour. Include only user_id and username in the token. Do not expose the password or private
settings. Return a diff and tests.
At Add context
, enter /file
and choose requirements.txt
. Then enter /func
, choose app.py
,
and select login
. Use the arrow keys to move through the completion menu and Tab to select an
item. Press Enter at Add context
to continue.
setup
prepares local state, and init
indexes the Python files. log
records approved project
context. search
shows ranked candidates, and brief
starts the review that produces the Markdown file.
If setup
is interrupted, run it again. It resumes only when every existing state entry exactly matches a generated default. Unknown or modified entries are left untouched, and setup stops with an error.
Register paths that siloBrief must skip before building the index:
sb ignore private_adapter --as "External delivery adapter" --alias delivery-boundary
sb init
If a boundary is no longer needed, remove it by its stored path or alias and rebuild the index:
sb unignore delivery-boundary
sb init
unignore
changes the local configuration without opening the target. It marks the current index as
stale, so sb brief
remains blocked until sb init
finishes. Files under the removed boundary may then appear as review candidates.
Use sb log
for a project fact that the code alone does not explain:
sb log src/parcel_sync/service.py --comment "HTTP 503 responses may be retried."
Enter only information approved for external disclosure. Do not put private source code, secrets, or real names from excluded areas in a project note.
Start a review with a concrete task:
sb brief "Update retry_request to retry HTTP 503 but not 500. Return a unified diff and tests." --out .silobrief/exports/retry-with-note.md
Omit PROMPT
to open the interactive request builder. /file
lets you choose an allowed project
file. /func
lets you choose an indexed Python file, then one of its functions or methods.
During brief
:
- Confirm the task. Files and functions chosen in the request builder are added to the task. Indexed Python choices are also preselected for review, and you can add other candidates.
- Review one-hop related context and type an
rN
value only for an item you want to add. Blank input approves none. - Review each proposed project field.
- Choose whether to include the displayed source code. The default answer is no.
- If a boundary identifier appears in an approved excerpt body or definition header, type
EXPOSE
after reviewing it. - Review the complete brief.
- Type
WRITE
to create the file.
The result is one Markdown brief containing the task, approved project context, and any source code you select and approve. Selected source is included verbatim. If you decline every source selection, the file contains only the task and approved project context. Open the file before moving it to a different environment.
The terminal interface and generated brief default to English. Settings are stored per project and can be changed together or separately:
sb language --cli ko
sb language --brief en
sb language
The CLI setting changes fixed terminal guidance. The brief setting changes generated headings and instructions. Task text, project notes, source code, paths, symbols, and identifiers remain as entered or selected. Language settings do not affect indexing, candidate ranking, IDs, ordering, or source digests.
Write PROMPT
as a concrete task, not a list of keywords. Include the required deliverables and acceptance criteria so the receiving assistant can tell when the work is complete.
| Command | What it does |
|---|---|
sb setup [PATH] |
|
| Adds or checks local siloBrief state in an existing project. | |
sb example PATH |
|
| Creates a minimal Flask practice project. | |
sb ignore PATH --as TEXT [--alias NAME] |
|
| Excludes a path and records a public label for that boundary. | |
sb unignore SELECTOR |
|
| Removes one registered boundary by its exact stored path or alias. | |
sb init |
|
| Builds the local search list from allowed Python files. | |
sb log PATH --comment TEXT |
|
| Saves an approved project note. | |
sb search "PROMPT" |
|
| Lists a bounded set of code candidates and the request terms that matched each one. | |
sb language [--cli {en,ko}] [--brief {en,ko}] |
|
| Sets terminal and generated-brief languages independently. | |
sb brief ["PROMPT"] [--out FILE] |
|
Opens the interactive request builder when PROMPT is omitted. The default output is .silobrief/exports/brief.md . |
|
sb chat "PROMPT" --out FILE |
|
Previous name for sb brief , kept for existing users. |
|
sb --version |
|
| Prints the installed siloBrief version. |
Commands other than setup
and example
find the project root from the current directory. brief
requires an interactive terminal, a current index, and a new .md
output path. Output inside the
project must be below .silobrief/exports/
. Existing files are never overwritten.
When standard error is an interactive terminal, sb init
shows one progress line for source collection, analysis, index construction, source-change verification, and writing. Redirected output and CI runs omit the progress display. The success message remains on standard output.
siloBrief does not read registered excluded paths or follow symbolic links while indexing. References to excluded code use the public label you approved. Before it writes a brief, you review the complete output and choose which source excerpts to include.
Source and state access stays bound to the project root and directory entries that were originally opened. During review and output, siloBrief also rechecks the configuration, current index, approved source snapshot, and destination. If their contents or filesystem identities change, it stops. It creates state and output files without replacing an existing entry and escapes terminal control characters from untrusted text before displaying it.
It does not detect secrets in allowed files or text entered with sb log
. Approved source code may contain comments, docstrings, strings, and internal identifiers. siloBrief is not a security scanner or an export-approval system for a closed environment. Review every generated file under your organization's disclosure rules before sharing it.
On Ubuntu, secure brief output requires the destination filesystem to support O_TMPFILE
and allow
links through /proc/self/fd
. If either feature is unavailable, siloBrief stops without creating the
requested file. For a project under WSL's /mnt/c
, run the native Windows sb
command or move the project and output location to the WSL Linux filesystem.
The latest public release is v1.2.1 and follows the supported 1.x compatibility contract. In the
frozen retrieval benchmark, sb search
reaches an expected symbol for 11 of 12 tasks, with a mean reciprocal rank of 72.2%. Candidate search is lexical and advisory. When it misses, use the exact indexed Python file path during review.
The deterministic end-to-end flow was verified on Django Ninja, pytest, and Jinja checkouts without changing their Python source files. The benchmark is small and does not establish effectiveness across other AI models or private projects.
Installed wheel verificationManual model gateClaude gate resultv0.7 retrieval resultv0.8 related-context resultSolo field-trial procedurev1.0.1 release verificationv1.0 scope-related context study
| Code | Meaning |
|---|---|
0 |
|
| Success | |
1 |
|
| Unexpected internal error | |
2 |
|
| Input, path, or configuration error | |
3 |
|
| Indexing or Python parsing error | |
4 |
|
| Boundary validation, approval, or output was blocked |
See the security policy for vulnerability reporting guidance.
Contributions are welcome. Read the contributing guide before opening an issue or pull request. Everyone participating in the project must follow the code of conduct.
siloBrief is distributed under the Apache License 2.0. See LICENSE.