Forge Agent

Forge Agent is a terminal-first coding assistant for a single local repository. It uses Anthropic tool calling to inspect files, edit code, and search a Markdown knowledge base without pretending to be a full IDE replacement.

This project is positioned as a compact portfolio build: small enough to understand end to end, but structured enough to demonstrate tool-driven agent design, prompt orchestration, workspace safety, and retrieval-backed context.

What It Does

• Runs a conversational coding agent in the terminal
• Gives the model structured tools for reading, listing, writing, and editing files
• Restricts file operations to the current workspace
• Searches project docs from docs/
• Supports local slash commands for help, reset, and transcript export
• Supports two documentation modes:
  • Weaviate semantic search when the local vector stack is running
  • Local Markdown fallback search when Weaviate is unavailable

Stack

• Python
• Anthropic Messages API
• Pydantic tool schemas
• Optional Weaviate + Transformers inference for vector search

Project Layout

• main.py - interactive agent loop
• tools.py - tool definitions and workspace-safe file operations
• rag.py - vector search integration plus local Markdown retrieval fallback
• index_doc.py - documentation indexing entry point for Weaviate
• docs/ - project knowledge base used by the agent
• snake-game/ - a small side experiment kept as an example artifact

Quick Start

1. Create a virtual environment and install dependencies:

   pip install -r requirements.txt

2. Create your environment file:

   copy .env.example .env

3. Add your Anthropic API key to .env:

   ANTHROPIC_API_KEY=your_key_here

4. Start the agent:

   python main.py

CLI Commands

• /help shows the local command list
• /clear resets the active chat state
• /save exports the current chat transcript to sessions/

Optional Vector Search

The agent can search docs/ without any extra services, but semantic search gets better if you run the local Weaviate stack.

1. Start Weaviate:

   docker-compose up -d

2. Index the documentation:

   python index_doc.py --clear

If Weaviate is down, search_documentation automatically falls back to local Markdown ranking.

Example Prompts

• Summarize the architecture of this repository
• List the Python files and explain what looks unfinished
• Create a new docs/setup-notes.md file with onboarding steps
• Search the documentation for the prompt strategy
• Refactor the file tools so they do not write outside the repo

Why This Repo Works For A Portfolio

• The scope is honest. It is a local coding assistant, not a fake autonomous platform.
• The architecture is inspectable. The full loop fits in a handful of files.
• The tradeoffs are visible. You can see how prompt design, tool schemas, and retrieval behavior interact.
• The safety model is simple but real. File writes are workspace-scoped.

Notes

• The default model is configurable with ANTHROPIC_MODEL.
• The docs in docs/ are intentionally project-specific so retrieval stays relevant.
• The repo still includes a small game/demo artifact, but it is now clearly separated from the core agent.