From 9183c642252efa54ad6540cb1fc6960ae853d995 Mon Sep 17 00:00:00 2001 From: codex Date: Thu, 28 May 2026 01:54:55 -0400 Subject: [PATCH] docs: add agent guidance --- AGENTS.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..41855c8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,51 @@ +# Codex-bottle + +## What this is + +Codex-bottle spins up an isolated container for running Codex with a +curated set of skills and env vars. The point is to run Codex with broad +permissions inside a sandbox, so a misbehaving agent cannot reach the host. +A Python CLI (entry point `cli.py`, package `claude_bottle/`) orchestrates +the container lifecycle and the copying of skills and env vars into it. + +## Goals + +- Minimize risk of running Codex with full permissions +- Allow me to easily spin up agent tasks in parallel +- Create isolated, well defined, easily updated, shareable agents + +## Non-goals + +- Communicating between agents directly +- Self hosted VMs (v1 uses local Docker containers, not VMs) +- Advanced agent auditing (lean on git history for auditing) + +## Repository layout + +- `README.md` — short public-facing description. +- `AGENTS.md` — this file, orientation for future Codex sessions. +- `.gitignore` — OS junk. +- `Codex-bottle.json` — manifest of named agents (env / skills / prompt + per agent), consumed by `cli.py`. See "Manifest" under + "Intended design". +- `docs/INDEX.md` — pointer to the research notes. +- `docs/prds/` — product requirement docs. +- `docs/research/` — research notes (empty for now, kept tracked via `.gitkeep`). + +## Conventions + +- Product requirement docs live in `docs/prds/`. +- Research notes live in `docs/research/`. +- Low dependencies by default. The project is Python, stdlib-first (no + runtime pip dependencies in the package itself; the only language + runtime is the Python 3.13 used by the CLI + sidecars). Ask before + adding new tools, runtimes, or package managers. +- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/): + `[(scope)][!]: `, where `` is one of `feat`, `fix`, + `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`. + A `commit-msg` hook in `.githooks/` enforces this. Activate it once per clone + with `git config core.hooksPath .githooks`. + +## When you're unsure + +Ask. Default to drafting in chat over editing files when the request is ambiguous.