FoundryCLI

A local-first AI coding agent. It reads, writes and edits files, searches codebases, runs shell commands, and streams its output as it happens.

Runs on your own machine with a local model — no cloud account and no database server required.

---

Install

Install the tool. The package carries everything it needs — there is nothing to clone and nothing else to set up:

pip install foundrycli

That gives you the foundry command. Without installing, every example below works as python -m foundry.cli.main ....

Prefer a local build, or the release is not on PyPI yet? Build the wheel from a checkout (pip install build first):

python -m build    # writes dist/foundrycli-0.3.0-py3-none-any.whl
pip install dist/foundrycli-0.3.0-py3-none-any.whl

Working on the source? An editable install from a checkout also brings in the test and lint tooling:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Optional extras:

pip install "foundrycli[bedrock]"    # AWS Bedrock needs boto3
pip install "foundrycli[postgres]"   # PostgreSQL needs psycopg

From a checkout, write -e ".[bedrock]" and -e ".[postgres]" instead.

Quick start

foundry init        # creates the database and schema, reports the provider
foundry chat        # start the agent
foundry chat "list the python files in foundry/"

For a local model:

ollama serve
ollama pull qwen2.5:3b     # a tool-capable model

Commands

Command	What it does
foundry init	Create the database and schema, then report the LLM provider.
foundry status	Show the database state and which provider is active.
foundry providers	List every backend and whether it is reachable.
foundry setup	The settings screen — provider, API key, model, theme.
foundry chat	Start the interactive agent.
foundry chat "prompt"	Run a single prompt.

Inside the REPL: exit, clear (new conversation), status (details), settings (open the settings screen).

--provider <name> forces a backend for one run:

foundry --provider anthropic chat "hello"

Settings

foundry setup opens a small terminal UI. Pick a provider, type the key, choose a theme — it writes to .env for you, and the key is never echoed to the screen.

FoundryCLI - settings

  > Provider      currently auto
    API key       enter a key for a provider
    Model         change the model name
    Theme         currently default
    Show current settings
    Quit

You do not have to use a cloud provider. ollama needs no key at all.

Writing to .env never damages the rest of the file — the comments, blank lines and commented-out alternatives all survive.

Six themes ship with the tool: default, midnight, amber, mono, forest and violet. NO_COLOR is respected.

The live status view

While a task runs, a small panel under the answer shows the elapsed time, the provider, the step count and the recent tool calls:

 v list the files in foundry/llm
   12.5s  ·  auto  ·  [##--------] step
   list_directory ok

It repaints in place, so it does not fill the scrollback. Turn it off with foundry chat --no-status when you are piping the output somewhere.

The LLM gateway

One gateway, five backends. Every one of them speaks the same provider-neutral protocol, so the agent loop never changes.

Provider	API	Key	Notes
Ollama	OpenAI-compatible	–	Local, free. Needs a tool-capable model such as qwen2.5:3b.
AWS Bedrock	Converse	AWS creds	Uses the standard AWS credential chain.
OpenAI	Chat Completions	OPENAI_API_KEY
Anthropic	Messages	ANTHROPIC_API_KEY	Native Messages format, not OpenAI-compatible.
MiniMax	Chat Completions	MINIMAX_API_KEY	OpenAI-compatible.
auto	–	–	Probes each backend and uses the first that answers.

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

Each provider has its own model and base URL in .env, so switching backends never leaks a stale setting:

OLLAMA_MODEL=qwen2.5:3b
OLLAMA_BASE_URL=http://localhost:11434/v1
BEDROCK_MODEL_ID=moonshotai.kimi-k2.5
AWS_REGION=us-east-1
OPENAI_MODEL=gpt-4o-mini
ANTHROPIC_MODEL=claude-sonnet-4-5
MINIMAX_MODEL=MiniMax-M2

Check what is reachable at any time:

foundry providers

The database

DATABASE_URL decides the backend, and the database creates itself:

• SQLite (default) — a foundry.db file next to where you are working. In a source checkout that is the checkout root (the folder holding pyproject.toml); for an installed copy it is the directory you ran the command from. It is never written inside site-packages.
• PostgreSQL — if the database is missing, FoundryCLI connects to the postgres maintenance database and issues CREATE DATABASE, then applies the schema.

Migrations ship inside the package, at foundry/migrations/, and run automatically at startup. An installed copy brings its own database up to date; the root alembic.ini is only for running alembic by hand during development.

Tools

Tool	Permission	Purpose
read_file	read	Read a text file, with offset and limit.
write_file	write	Create a file or write complete content.
edit_file	write	Replace one exact piece of text. Keeps a .backup.
delete_file	write	Delete a file.
search_files	read	Search for text inside a directory.
list_directory	read	List a directory, optionally recursive.
ast_analysis	read	Imports, classes, functions, and calls of a Python file.
symbol_search	read	Find a class or function by name.
project_structure	read	A tree view of a project.
run_command	execute	Run a shell command.

write and execute tools ask for approval before they run. Every file tool is confined to the project root by PathPolicy.

Development

python run_checks.py    # tests, compile check, unused imports, ruff
pytest tests/           # just the tests

372 tests, 0 failing.

The tests and the documentation live in the repository, not in the package. pip install foundrycli gives you the tool; the test suite and the guides are for working on the source.

Documentation

Documentation/FOUNDRY_GUIDE.md is the complete guide — the intro, the setup, every feature defined, how it is built, and how to extend it.

Documentation/INTERVIEW_GUIDE.md is the deep dive — a line-by-line walkthrough of the whole project, why every file exists, the bugs the audit found, and how to explain the design to an interviewer.

Documentation/PUBLISHING.md is the release guide — how to install the tool and how to publish it to PyPI.

All three ship with the repository. They are not part of the installed package.

License

MIT