Forge

A full-stack AI chat application with a FastAPI backend and TypeScript/React CLI frontend. Forge provides an interactive terminal-based interface for chatting with AI models powered by Ollama, with support for tools.

• Terminal-based Chat Interface: Beautiful CLI interface built with React and Ink
• Ollama Integration: Seamless integration with Ollama for local AI model inference
• Streaming Responses: Real-time streaming of AI responses for better UX
• Session Management: Persistent chat history with session support
• Command System: Built-in commands for model management and navigation
• Tool Confirmation: Interactive approval prompts before the agent runs tools that require confirmation

• 1. Add file reading/writing tools
• 2. Add tool confirmation capabilities.
• 3. Add model downloading util at the frontend.
• 4. Add command running tools for the models.
• 5. Add MCP server support.
• 6. Fix rerendering bugs in the frontend.

• FastAPI: Modern Python web framework for building APIs
• SQLAlchemy: ORM for database management
• Ollama: Local LLM inference engine
• Agno: Agent framework for AI interactions
• Tavily: Internet search API integration
• SQLite: Lightweight database for chat history

• TypeScript: Type-safe JavaScript
• React: UI library
• Ink: React renderer for CLI applications
• Pastel: CLI framework for building terminal apps

Before installing Forge, ensure you have the following installed:

• Python 3.8+: Required for the backend
• Node.js 16+: Required for the frontend
• Ollama: Must be installed and running locally
  • Download from ollama.ai
  • At least one model must be downloaded (e.g., qwen2.5:14b)
• Tavily API Key (optional): Required only for internet search functionality
  • Sign up at tavily.com to get your API key

1. Clone the repository:

   git clone https://www.github.com/loeclos/forge.git
   cd forge

2. Install all dependencies (backend virtualenv + frontend packages):

   make install

   Or install manually with conda/pip and npm/pnpm as described in INSTALLATION.md.

3. Configure Environment Variables:

   Create a .env.local file in the backend directory:

   TAVILY_API_KEY=your_tavily_api_key_here

   Create a .env.local file in the frontend directory:

   MAIN_ENDPOINT=http://127.0.0.1:8000

4. Run the whole app (backend + CLI together):

   make run

   Or start the pieces separately with make backend and make frontend.

For detailed installation instructions, see INSTALLATION.md.

A development shell is provided via shell.nix. Inside it you get Python, Node, pnpm, Ollama, and make, with the backend virtualenv and frontend dependencies set up automatically:

nix-shell
make run

1. Start the Backend Server:

   cd backend
   uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

2. Start the Frontend CLI (in a new terminal):

   cd frontend
   npm run build
   node dist/cli.js
   # or
   pnpm build && node dist/cli.js

1. Start Backend:

   cd backend
   uvicorn app.main:app --host 0.0.0.0 --port 8000

2. Run Frontend:

   cd frontend
   npm run build
   node dist/cli.js

The backend configuration is managed in backend/app/core/config.py. On startup it automatically loads backend/.env.local and backend/.env, so settings can be overridden with environment variables or a dotenv file. Key settings:

• APP_NAME: Application name (default: "Forge")
• MODEL: Default Ollama model to use (default: "qwen2.5:14b")
• TAVILY_API_KEY: API key for Tavily internet search (optional; internet search is unavailable without it)
• DATABASE_URL: SQLite database path (default: backend/app/db/database.db)

The SQLite databases (database.db and chat_history.db) are stored in backend/app/db/, which is created automatically on startup.

The frontend configuration is managed via environment variables in .env.local:

• MAIN_ENDPOINT: Backend API endpoint (default: "http://127.0.0.1:8000")

forge/
├── Makefile               # make install/run/test/etc.
├── shell.nix              # Nix development shell
├── INSTALLATION.md        # Detailed installation guide
├── API.md                 # API reference
├── README.md              # This document
│
├── backend/                 # FastAPI backend application
│   ├── app/
│   │   ├── api/             # API route handlers
│   │   │   └── v1/          # API version 1 routes
│   │   ├── config/          # Configuration modules
│   │   ├── core/            # Core application settings
│   │   ├── db/              # SQLite database files (auto-created)
│   │   ├── logs/            # Application logs
│   │   ├── services/        # Business logic services
│   │   ├── tools/           # AI agent tools
│   │   ├── database.py      # Database configuration
│   │   └── main.py          # FastAPI application entry point
│   ├── requirements.txt     # Python dependencies
│   ├── requirements-dev.txt # Test/lint dependencies
│   ├── environment.yml      # Conda environment
│   └── pytest.ini           # Pytest configuration
│ 
├── frontend/                # TypeScript/React CLI frontend
│   ├── source/              # Source code
│   │   ├── commands/        # CLI commands
│   │   ├── components/      # React components
│   │   ├── hooks/           # React hooks
│   │   ├── services/        # Service layer
│   │   ├── types/           # TypeScript type definitions
│   │   ├── utils/           # Utility functions
│   │   └── cli.tsx          # CLI entry point
│   ├── dist/                # Compiled JavaScript output
│   ├── test.tsx             # Frontend tests
│   └── package.json         # Node.js dependencies

1. Launch the frontend CLI application
2. You'll be prompted with a security question about trusting files in the current directory
3. Select "Yes, proceed" to continue
4. Start typing your message and press Enter
5. The AI will respond in real-time with streaming output
6. If the agent wants to run a tool that requires confirmation, a prompt will appear asking whether to allow it — choose "Yes, allow it" or "No, reject it". The stream pauses and resumes once you answer.

Type / followed by a command name to access built-in commands:

• /models - List all available Ollama models
• /model - Show the currently active model
• /change - Change the active model
• /exit - Exit the application

Welcome to Forge!
Forge can write, test and debug code right from your terminal.
Describe a task to get started or enter ? for help.

❯ What is the capital of France?
The capital of France is Paris.

For complete API documentation, see API.md.

The backend provides the following main endpoints:

• GET /api/models/all - Get all available models
• GET /api/models/current - Get current model
• POST /api/models/change - Change current model
• POST /api/models/download/{model_name} - Download a model
• GET /api/models/alive - Check if Ollama is running
• POST /api/chat - Send a chat message
• POST /api/chat/confirm-tool - Approve or reject a pending tool call
• GET /api/utils/getcwd - Get current working directory

If you just see a blank message box for a while, this could be for two reasons:

1. The model you chose is too big and runs really slowly on your machine.
2. The model you chose doesn't have tool integration.

To fix 1, try pulling a smaller model from the same family (i.e. qwen3:0.6b instead of qwen3:7b) or you can just wait. The response should show up eventually.

For 2, you must make sure that the model you got supports tools. All models that allow tools are listed here: https://ollama.com/search?c=tools

If you see "Ollama either not installed or not running":

1. Ensure Ollama is installed and running
2. Check that at least one model is downloaded: ollama list
3. Verify Ollama is accessible: ollama ps

If the frontend can't connect to the backend:

1. Verify the backend is running on the correct port
2. Check that MAIN_ENDPOINT in .env.local matches the backend URL
3. Ensure no firewall is blocking the connection

If you get "Model not found" errors:

1. List available models: /models command
2. Download the model: Use Ollama CLI: ollama pull <model_name>

For more troubleshooting tips, see INSTALLATION.md.

• Installation Guide - Detailed setup instructions
• API Reference - Complete API documentation

Contributions are welcome! Please feel free to submit a Pull Request.

For issues, questions, or contributions, please open an issue on the repository.