Swap the LLM backend without touching the agent loop:

from pycodeloop import Config
from pycodeloop.providers import AnthropicProvider, OpenAIProvider

# Anthropic
config = Config(provider=AnthropicProvider(model="claude-sonnet-5"))

# OpenAI
config = Config(provider=OpenAIProvider(model="gpt-5"))

Env-based defaults, resolved by pycodeloop.settings.Settings when Config() gets no explicit provider:

export PYCODELOOP_PROVIDER=anthropic   # or: openai
export PYCODELOOP_MODEL=claude-sonnet-5
export ANTHROPIC_API_KEY=sk-...    # or OPENAI_API_KEY

Point GenericProvider at any OpenAI-compatible HTTP endpoint, or configure one entirely from a JSON file — no Python required:

from pycodeloop.providers import get_provider

provider = get_provider("./provider.example.json")

pycodeloop run "list the files here" --provider ./provider.example.json

See docs/examples/provider.example.json and the JSON provider guide.

Bring your own backend by implementing the Provider ABC:

from pycodeloop.abc.provider import Provider, ProviderResponse

class MyProvider(Provider):
    def complete(self, system_prompt, messages, tools) -> ProviderResponse:
        ...

The Config class validates and injects the pieces an agent run needs:

from pycodeloop import Config
from pycodeloop.providers import AnthropicProvider
from pycodeloop.core.tools import DEFAULT_TOOLS

config = Config(
    provider=AnthropicProvider(model="claude-sonnet-5"),
    tools=DEFAULT_TOOLS,
    system_prompt="You are a terse code reviewer.",
    max_turns=25,
)

Passing anything that isn't a Provider instance raises NotProviderInstance at construction time, not mid-run.

By default the session grows without bound — every turn's full history is resent to the provider every call. Pass max_history_turns to cap it: older turns are dropped as a whole unit (never mid tool_calls/tool_result, which every provider rejects) before each provider call.

config = Config(provider=provider, max_history_turns=20)

Two more pluggable pieces, both optional:

• Sessions — persists a Session by key so a conversation survives process restarts. Pass one to Config(storage=...) and call CodeLoop.run(prompt, session_key=...). Two built-in implementations: FileSessions writes one JSON file per session under ~/.pycodeloop/sessions/; SqliteSessions (from pycodeloop.core.store.sqlite_sessions import SqliteSessions) is a SQLAlchemy model backed by a single queryable ~/.pycodeloop/pycodeloop.db instead.
• Confirm — an ABC form of the confirm callback (Agent(confirm=...)) for when you want a reusable class instead of a closure — same bool | str contract, just .ask(name, preview) instead of calling it directly. A plain callable still works everywhere confirm is accepted.

from pycodeloop import CodeLoop, Config
from pycodeloop.core.store.file_sessions import FileSessions

config = Config(provider=provider, storage=FileSessions())
flow = CodeLoop(config=config)

flow.run("remember this", session_key="user-42")
# ... later, even in a new process:
flow.run("what did I say?", session_key="user-42")

Ships with the actions an agent needs to actually change code:

Add your own by subclassing Tool:

from pycodeloop.abc.tool import Tool, ToolResult

class MyTool(Tool):
    name = "my_tool"
    description = "Does a thing."
    parameters = {"type": "object", "properties": {"x": {"type": "string"}}}

    def run(self, x: str) -> ToolResult:
        return ToolResult(output=f"did {x}")

Mark a tool dangerous = True and it gets a confirmation gate before it runs — write_file, edit_file, delete_file, bash, git_commit, http_request, and every MCP tool already are. Override preview(**kwargs) to control what's shown at confirmation time (defaults to a diff for file tools, the command line for bash):

from pycodeloop.core.agent import Agent

def confirm(name: str, preview: str) -> bool:
    print(preview)
    return input(f"run {name}? [y/N] ").lower() == "y"

agent = Agent(provider=provider, confirm=confirm)

Agent exposes hooks for everything the terminal UI needs — streamed text, per-turn and cumulative token usage:

from pycodeloop.core.agent import Agent

agent = Agent(
    provider=provider,
    on_text_delta=lambda chunk: print(chunk, end=""),
    on_usage=lambda turn, total: print(f"\n{turn.input_tokens}in/{turn.output_tokens}out, total {total.input_tokens}in/{total.output_tokens}out"),
)

agent.run("...")
print(agent.usage)  # Usage(input_tokens=..., output_tokens=...)

on_text_delta only fires when the provider supports streaming (Anthropic and OpenAI both do); leave it None to get the assembled response in one shot instead.

pip install pypycodeloop[mcp]

Connect to any Model Context Protocol server over stdio and expose its remote tools to the agent alongside the built-in ones:

from pycodeloop import CodeLoop, Config
from pycodeloop.core.mcp import MCPServer, load_mcp_tools
from pycodeloop.core.tools import DEFAULT_TOOLS
from pycodeloop.providers import AnthropicProvider

server = MCPServer(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "."])
tools = DEFAULT_TOOLS + load_mcp_tools(server)

config = Config(provider=AnthropicProvider(model="claude-sonnet-5"), tools=tools)
flow = CodeLoop(config=config)

Or from the CLI, one --mcp flag per server:

pycodeloop run "list every allowed directory" \
  --mcp "npx -y @modelcontextprotocol/server-filesystem ."

load_mcp_tools keeps the server subprocess alive on a background event loop for the life of the process, and adapts each remote tool schema into a regular Tool — the agent can't tell an MCP tool from a local one.

Run the agent directly from the command line:

# Bare pycodeloop drops into the full-screen chat
pycodeloop

# One-shot, non-interactive (scripting/CI)
pycodeloop run "add a docstring to pycodeloop/core/agent.py"

# Override provider/model per invocation
pycodeloop run "..." --provider openai --model gpt-5

# Skip confirmation prompts for dangerous tools
pycodeloop run "..." --yes

# Skip skills auto-discovery
pycodeloop run "..." --no-skills

The CLI behaves like a terminal coding agent:

• Streams the model's text as it arrives instead of waiting for the full reply.
• Asks before running write_file, edit_file, delete_file, bash, git_commit, http_request, or any MCP tool — shows a diff (or the shell command) and waits for confirmation, auto-running after 3s of no response. --yes skips this.
• Reports token usage after every turn: input/output tokens for that turn plus the running session total.
• Discovers skills automatically — SKILL.md/CLAUDE.md (Claude Code), .mdc/.cursorrules (Cursor), and AGENTS.md files already on disk are indexed and exposed to the agent via a read_skill tool, cached in ~/.pycodeloop/config.json until something changes. --no-skills turns this off; --skills-refresh bypasses the cache.

CodeLoop is a thin wrapper around Agent + Session for when you want direct control over the tool-use loop, hooks, or multi-turn state:

from pycodeloop.core.agent import Agent
from pycodeloop.providers import AnthropicProvider

def on_tool_call(name, args):
    print(f"-> {name} {args}")

agent = Agent(
    provider=AnthropicProvider(model="claude-sonnet-5"),
    on_tool_call=on_tool_call,
)

reply = agent.run("fix the failing test in tests/test_agent.py")