Coldbrew

Coldbrew is a calm local coding-agent CLI inspired by Mihail Eric's article.

It uses LLMlibrary conversations with local function tools:

• list_files
• list_tree
• search_files
• git_diff
• run_command
• read_file
• read_many_files
• write_file
• edit_file
• apply_patch

Write/edit/patch tools are enabled by default. Pass --dry-run to preview changes without writing.

Safety

This is a local coding-agent demo, not a full sandbox. It can read and write files under the configured project root.

Use --dry-run when you want read-only previews.

Setup

pnpm install
cp .env.example .env
pnpm build
pnpm install:cli

Set OPENAI_API_KEY in your environment or .env. Optionally set OPENAI_MODEL; the CLI defaults to gpt-5.4.

Install rg/ripgrep for fast code search. On macOS:

brew install ripgrep

After installing the wrapper, the coldbrew command is available from your shell. The installer also provides agent as a convenience alias.

By default pnpm install:cli writes small wrappers to ~/.local/bin/coldbrew and ~/.local/bin/agent. That directory is commonly on PATH. To choose another directory:

COLDBREW_BIN_DIR=/usr/local/bin pnpm install:cli

Run

coldbrew "List the files in this project"
coldbrew "Search for createFileTools in src"
coldbrew --dry-run "Preview a README.md update"
coldbrew --max-output-tokens 24000 "Create a single-file HTML game"
coldbrew --sessions
coldbrew --resume 20260620T120000Z-list-files-abc123ef "continue from there"

You can also run through pnpm during development:

pnpm coldbrew "List the files in this project"

Use --root <path> to point the tools at another project root.

Local History And Resume

Coldbrew persists LLMlibrary conversations locally by passing a file-backed SessionStore into LLMClient.fromEnv(). By default, sessions are saved under:

~/.coldbrew/sessions

Each agent run prints its session id. Resume it later with:

coldbrew --resume <session-id>
coldbrew --resume <session-id> "continue the task"

When a saved session is resumed, Coldbrew prints the stored message history before accepting the next prompt. Tool calls and tool results are summarized so the terminal stays readable.

Session commands:

• --sessions - list saved local sessions
• --session <id> - use or create a named session
• --delete-session <id> - delete a saved session
• --history-dir <path> - use another local history directory
• --no-history - keep the current run out of durable history

Interactive commands:

• :session - show the current session id and history directory
• :sessions - list saved sessions
• :clear - clear in-memory conversation state and remove the saved session until the next message

Agent Instructions And Skills

Coldbrew uses LLMlibrary's native unified-llm-client/agent-files support for repository instructions and skills.

Repository instructions are loaded from AGENTS.md files under the project root. LLMlibrary also accepts AGENTS.override.md, agent.md, and Agent.md.

Skills are reusable instruction packs. They add task-specific guidance to the model; they do not add new shell commands or executable tools.

Default skill search path:

• <project>/.agents/skills/*/SKILL.md

Example:

.agents/skills/frontend-review/
  SKILL.md

---
name: frontend-review
description: Review React UI changes for usability, accessibility, and regressions.
triggers: react, ui review, accessibility
---

# Frontend Review

Inspect changed UI files before commenting. Prioritize concrete bugs, layout breakage, accessibility regressions, and missing tests.

List discovered skills:

coldbrew --skills

Use a skill explicitly:

coldbrew --skill frontend-review "Review the UI changes"

Add a custom search directory:

coldbrew --skills-dir ./team-agent-root --skill docs "Update the README"

Disable skills:

coldbrew --no-skills "List the files in this project"

--skills-dir points at another native agent root containing .agents/skills. When no skill is selected explicitly, Coldbrew activates matching skills by comparing the task with skill names, descriptions, and trigger metadata.

Interactive Chat Mode

Start the agent once:

coldbrew

Then type normally:

list the files in src
summarize README.md
:allow-edits
:session
:sessions
:skills
:use-skill frontend-review
create the file we discussed
exit

Each line is sent to the same LLMlibrary conversation, so follow-up requests can refer to prior turns. Type exit, quit, or :q to close the session.

Coldbrew defaults to 16000 output tokens per model turn so file-writing tool calls have room to include complete file contents. Use --max-output-tokens <n> for unusually large generated files.

Interactive commands:

• :status - show current model/root/edit mode and memory count
• :session - show the current session id and history directory
• :sessions - list saved local sessions
• :allow-edits - enable writes for the current session
• :dry-run - return to dry-run edit mode
• :skills - list discovered skills
• :use-skill <name> - keep a skill active for later prompts
• :clear-skills - remove manually active skills
• :reload-skills - reload skills from disk
• :clear - clear conversation memory

Verify

pnpm test
pnpm build

Developer Docs

• DEVELOPERS.md: architecture, tool loop, local command setup, and safety notes.
• CONTRIBUTING.md: contribution workflow and project expectations.
• SECURITY.md: vulnerability reporting and safety boundaries.
• CODE_OF_CONDUCT.md: community expectations.

License

MIT