This repository contains experimental CLI file-agent projects and build iterations. Each project is a terminal app that uses OpenAI tool-calling to inspect local files and directories; the builds progress from a minimal agent to a manifest-driven, MCP-powered version.

All builds share the same core idea: an interactive chat loop, filesystem tools (get_working_directory, list_directory, read_file, search_files), and Rich CLI with reset, history, help, exit.

• file_agent — Start here: one place for prompts, schemas, and tool code.
• file_agent_manifest — Behavior and identity move into YAML/Markdown (role + skills).
• file_agent_mcp_manifest — Tool set is configured via mcp.json (which tools to expose), still in-process.
• file_agent_mcp — Tools are provided by an MCP server subprocess; add or swap servers without changing agent code.

agent_fun_build/
  README.md                 # This file
  AGENTS.md                 # Guidance for coding agents in this repo
  file_agent/               # Base build: hardcoded tools + schemas
    README.md
    pyproject.toml
    src/file_agent/
  file_agent_manifest/      # Manifest build: role + skills from YAML/MD
    README.md
    pyproject.toml
    src/file_agent_manifest/
  file_agent_mcp_manifest/  # MCP-style manifest: tool set from mcp.json (in-process)
    README.md
    pyproject.toml
    src/file_agent_mcp_manifest/
  file_agent_mcp/           # Full MCP: tools from MCP server over stdio
    README.md
    pyproject.toml
    src/file_agent_mcp/

From the repo root, pick a project and run:

cd <project_dir>   # e.g. file_agent, file_agent_mcp
uv sync

Create a .env in that directory (or where you run from) with:

OPENAI_API_KEY=your_api_key_here

Then start the agent:

Project-specific setup, layout, and options are in each project’s README.md.

• Python: 3.12+
• Package manager: uv (recommended) or pip
• OpenAI: API key in .env as OPENAI_API_KEY

From the project directory:

uv build

Artifacts go to <project_dir>/dist/.

• Each project is a separate Python package with its own pyproject.toml and dependencies.
• AGENTS.md at the repo root describes scope, layout, and conventions for the file_agent/ tree; adapt as needed for the other builds.
• The repository may grow with more agent experiments over time.