briefcase
Pack your agent's briefcase with the right repos before it starts work.
Coding agents write better code when they can read real examples — but wiring up reference repos for every new project is tedious. Briefcase maintains a local registry of GitHub repos and scaffolds new projects with symlinked references, generated context files, and everything an agent needs to hit the ground running.
Install
pip install agent-briefcase
Or install from source:
git clone https://github.com/cegersdoerfer/briefcase.git
pip install -e .
Requires Python 3.10+ and git.
Usage
Register a repo
briefcase add <name> <repo-url>
GitHub /tree/ and /blob/ URLs are supported to reference a subdirectory or individual file within a repo:
briefcase add pi-src https://github.com/badlogic/pi-mono/tree/main/packages/agent/src
briefcase add pi-agent-loop https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/agent-loop.ts
Clones the repo into ~/.briefcase/repos/<name> and records it in the registry.
List registered repos
briefcase list
Remove a repo
briefcase remove <name>
Removes the tool from the registry and deletes its cloned repo from ~/.briefcase/repos/.
Update a repo (git pull)
briefcase update <name>
briefcase update --all
Scaffold a new project
briefcase new myproject --tools foo bar
When --tools is omitted, an interactive menu lets you pick from registered tools:
briefcase new myproject
Creates a project directory with this layout (using the default layout):
myproject/
src/ # your code goes here
tests/
refs/
foo -> ~/.briefcase/repos/foo # symlink, read-only reference
bar -> ~/.briefcase/repos/bar
toolset.yaml
AGENT_CONTEXT.md
The generated AGENT_CONTEXT.md and toolset.yaml give a coding agent the context it needs to use the referenced repos.
Project layouts
The --layout flag selects a project layout:
briefcase new myproject --tools foo --layout minimal
Built-in layouts:
| Layout | Directories | Files |
|---|---|---|
default |
src, tests | toolset.yaml, AGENT_CONTEXT.md |
minimal |
(none) | AGENT_CONTEXT.md |
Both layouts create a refs/ directory for tool symlinks.
Custom layouts
Place a YAML file in ~/.briefcase/layouts/ to define a custom layout:
# ~/.briefcase/layouts/mylay.yaml
dirs: [lib]
refs_dir: refs
files:
AGENT_CONTEXT.md: |
# {{ project_name }}
{% for tool in tools %}
- **{{ tool.name }}** — `{{ tool.rel_path }}`
{% endfor %}
Template variables: {{ project_name }}, {{ tool.name }}, {{ tool.rel_path }}, {{ tool.notes }}.
A same-named file in ~/.briefcase/layouts/ overrides a built-in layout.
Default layout config
Set a global default in ~/.briefcase/config.yaml:
default_layout: minimal
The --layout CLI flag takes precedence over the config file.
Custom home directory
Override the default ~/.briefcase location:
briefcase --home /path/to/registry list
BRIEFCASE_HOME=/path/to/registry briefcase list
--home takes precedence over the BRIEFCASE_HOME env var.
Development
pip install -e ".[dev]"
.venv/bin/python -m pytest
Metadata
Release files for agent-briefcase 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_briefcase-0.1.2.tar.gz | 10.2 kB | Without provenance | Details for agent_briefcase-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_briefcase-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for agent_briefcase-0.1.2-py3-none-any.whl |
Total release size: 20.3 kB
Release files / agent_briefcase-0.1.2.tar.gz
| Download URL | agent_briefcase-0.1.2.tar.gz |
|---|---|
| Size | 10.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
59c46ff4373b3b983bada686eefa369fda2f99671cc7b974946da4a56f93b156
|
|
BLAKE2b-256 checksum How to use checksums |
e1241bce9a3a5922c1d338a549ead4d682ba3179719da650eec3107d0c525c59
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Release files / agent_briefcase-0.1.2-py3-none-any.whl
| Download URL | agent_briefcase-0.1.2-py3-none-any.whl |
|---|---|
| Size | 10.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4b504eac034b936ab2bbb48bad4ed4cdf1c7403d1ebdce78a1b0f8c73b44fe37
|
|
BLAKE2b-256 checksum How to use checksums |
e56c585bc6d3237b6293d002be6544275cfa82bfe34fcf061c94db3a9eaee418
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Security for agent-briefcase 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.