silobrief 1.1.0

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 dependencies: none
• 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.

Quick start

Install

Install the stable package from PyPI and verify the command:

python -m pip install silobrief
sb --version

Expected output:

siloBrief 1.1.0

Practice project

Create a practice project:

sb example ./silobrief-practice
cd silobrief-practice

The generated README.md guides you through one Flask shipping-price change while keeping a private carrier contract module outside the index and brief.

Start the task from the same directory:

python -m pip install -r requirements.txt
sb setup .
sb ignore internal --as "Private carrier contract rules" --alias carrier-boundary
sb init
sb log pricing.py --comment "Weight is a positive whole number in kilograms."
sb search "Add a 1000-unit remote-area surcharge to calculate_shipping_price. Apply it after the weight surcharge."
sb brief "Add a 1000-unit remote-area surcharge to calculate_shipping_price. Apply it after the weight surcharge. Preserve the Flask response shape and return a readable diff and focused unittests." --out .silobrief/exports/remote-surcharge.md

setup prepares local state, ignore registers the private module, and init indexes only the allowed 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.

How it works

Set project boundaries

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.

Add project context

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.

Review and write

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

During brief:

1. Confirm the task and choose the relevant function or class. If the suggested candidates miss the target, enter an exact indexed Python file path and select its functions or classes.
2. Review one-hop related context and type an rN value only for an item you want to add. Blank input approves none.
3. Review each proposed project field.
4. Choose whether to include the displayed source code. The default answer is no.
5. If a boundary identifier appears in an approved excerpt body or definition header, type EXPOSE after reviewing it.
6. Review the complete brief.
7. 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.

Choose interface and brief languages

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 a useful task

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.

Commands

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.

Safety and limitations

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.

Validation status

The latest public release is v1.1.0 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 verification
• Manual model gate
• Claude gate result
• v0.7 retrieval result
• v0.8 related-context result
• Solo field-trial procedure
• v1.0.1 release verification
• v1.0 scope-related context study

Exit codes

Security

See the security policy for vulnerability reporting guidance.

Contributing

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.

License

siloBrief is distributed under the Apache License 2.0. See LICENSE.