silobrief 1.0.1

Mission • Installation • Commands • Usage • Safety • Documentation • 한국어

In a closed network or an internal development environment, an external AI assistant cannot access the repository directly. Relevant code and project context must be prepared separately, but sending the entire repository is often unacceptable.

siloBrief is a local command-line tool that turns a development task and user-approved context from a closed Python project into reviewable Markdown. You choose which source code may be included, preview the complete result, and transfer the files under your organization's disclosure process. siloBrief does not connect to an AI service or send files over the network.

• Free software: Apache License 2.0
• Platforms: Windows and Ubuntu
• Python versions: 3.10 and newer
• Runtime dependencies: none

Mission

Our mission is to make context from a project that external AI cannot access useful without treating the whole repository as shareable. siloBrief provides:

• boundary registration before source indexing;
• local discovery of relevant Python functions and classes;
• explicit review of every context item and source-code selection;
• a complete preview before files are written; and
• deterministic Markdown that can be inspected and moved manually.

The generated files are inputs for another AI assistant. siloBrief does not generate the code change itself.

Installation

Install the stable package from PyPI and verify the command:

python -m pip install silobrief
sb --version

Expected output:

siloBrief 1.0.1

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 a single-line, five-stage progress bar for source collection, analysis, index construction, source-change verification, and writing. Redirected output and CI runs emit no progress display; the normal success message remains on standard output.

Both language settings default to English. They 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 the headings and instructions written by siloBrief. Task text, project notes, source code, paths, symbols, and identifiers remain exactly as entered or selected. Language settings do not change indexing, candidate ranking, IDs, ordering, or source digests.

Generated file

Each review produces one self-contained Markdown file:

retry-brief.md  task, approved project context, and any source code you approved

Send that file directly to the AI assistant. If you decline every source selection, the same file contains only the task and approved project context.

The repository also keeps a legacy v0.2 split-output example for validation history.

Usage

Guided practice project

Create a disposable project before using siloBrief with real source code:

sb example ./silobrief-practice
cd silobrief-practice

The generated README.md walks through one modification, one addition, and one removal task. The command does not run setup, index the project, call an AI service, or overwrite a non-empty directory.

Basic example

Copy the synthetic parcel-sync-fixture to a disposable directory. Run these commands from the copied project root:

sb setup .
sb ignore private_adapter --as "External delivery adapter" --alias delivery-boundary
sb init
sb search "Update retry_request to retry HTTP 503 but not 500."
sb brief "Update retry_request to retry HTTP 503 but not 500. Return a unified diff and tests." --out .silobrief/exports/retry-brief.md

setup prepares local state, ignore registers a path that must not be read, and init builds a local search list from the remaining Python files. search lets you inspect ranked candidates without starting disclosure review. brief uses the same candidates and then asks you to choose what may be included.

Remove a registered boundary

If an ignore entry is no longer correct, remove it by the exact stored path or alias, then rebuild the index:

sb unignore delivery-boundary
sb init

unignore changes only local configuration and does not open the removed path. It marks an existing index as stale, so sb brief remains blocked until sb init finishes. After rebuilding, files below that path may be offered for review and source disclosure.

Complete review

Add an approved project fact when code structure alone does not explain the task:

sb log src/parcel_sync/service.py --comment "HTTP 503 responses may be retried."
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 the source reveals an excluded boundary identifier, type EXPOSE only after reviewing it.
6. Review the complete self-contained brief.
7. Type WRITE to create the file.

Open the generated file before moving it to a different environment.

Write a useful task

Write PROMPT as a concrete task instead of a few keywords. State the required deliverables and acceptance criteria so the AI assistant can tell what a complete answer must contain.

Enter only information approved for external disclosure with sb log. Do not put private source code, secrets, or real names from excluded areas in a project note. Only source code you select and approve can be included verbatim in the generated brief; the default answer is no.

Terms

Safety and limitations

siloBrief:

• does not follow symbolic links while indexing;
• does not open registered excluded subtrees;
• does not open a boundary target while removing its registration;
• replaces references to excluded code with an approved public label in the main brief;
• requires a preview before writing output; and
• uses no network connection, language model, or automatic transfer.

siloBrief does not detect secrets inside allowed files or clean text entered with sb log. Approved source code can contain comments, docstrings, strings, and internal identifiers. It is not a security scanner, an export-approval system for a closed environment, or a guarantee against disclosure. Review every generated file under your organization's disclosure rules before sharing it.

Validation status

The latest public release is v1.0.1 and follows the supported 1.x compatibility contract. sb search now reaches an expected symbol for 11 of 12 frozen tasks, with mean reciprocal rank 72.2%. sb brief shows relation-labeled context proposals, defaults every proposal to unselected, and packages only explicitly approved context and source into one self-contained Markdown file.

The deterministic end-to-end flow passed on Django Ninja, pytest, and Jinja checkouts without changing Python source files or opening a network connection. Candidate search remains lexical and advisory; guided exact-path selection is still required when it misses. The benchmark is small and one task still misses. These results do not establish automatic context completeness, secret detection, export approval, market demand, or effectiveness across external AI models and private projects.

• Installed wheel verification
• Manual model gate
• Claude gate result
• v0.7 retrieval result
• v0.8 related-context result
• solo field-trial procedure

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.

Disclaimer

siloBrief is provided as-is. It helps you review files for manual disclosure, but it does not decide whether information is safe or authorized to share. Use it with your project's disclosure rules and review every output yourself.