← Back to projects
Local AI Coding Agent RuntimePrivate Repository

Forge

Building a Local AI Coding Agent for Apple Silicon

Forge is a private local agent runtime that lets open-weight models inspect repositories, modify code, run commands and tests, manage Git workflows, perform research, use persistent memory, and connect to external MCP tools without sending the core coding workflow to a cloud model provider.

Privacy-first AI developer agent for Apple Silicon

Role
Sole Designer and Engineer
Type
DestinyX Studios Product
Status
Active Development
Version
0.1.0
Platform
Apple Silicon
Repository
Private
Company
DestinyX Studios

Technologies

  • Python
  • Ollama
  • Qwen
  • SQLite
  • LanceDB
  • MCP
  • MLX
  • prompt_toolkit
Forge local AI coding agent terminal interface running qwen3-coder:30b in manual safe mode

Overview

Forge is a local AI coding agent designed to provide a capable, private development workflow on Apple Silicon. The language model runs through Ollama, while Forge provides the orchestration layer around it: a full-screen terminal interface, route-aware agent loop, structured tools, safety approvals, repository retrieval, semantic memory, sessions, skills, MCP integrations, and optional LoRA specialization.

Unlike a basic local-model chat interface, Forge can take controlled actions inside a development environment. It can inspect a repository, search code, edit files, run shell commands, execute tests, manage Git operations, create plans, delegate exploration to sub-agents, and recover file changes through checkpoints.

The Problem

Cloud coding assistants are powerful, but they can introduce source-code privacy concerns, recurring API costs, provider dependency, limited control over memory, and opaque tool-execution behavior.

The engineering question behind Forge was:

“How can a capable coding agent run locally while still providing structured tools, repository understanding, persistent memory, context management, safety controls, extensibility, and a polished developer experience?”

The Solution

  1. 01

    Terminal Interface

    A full-screen prompt_toolkit and Rich interface with a scrollable transcript, growing composer, live plans, tool status, model information, context usage, session controls, and mode switching.

  2. 02

    Routing and Product Layer

    Each turn is classified as social, local, research, or task. The route determines the prompt behavior, available tools, research workflow, and context strategy.

  3. 03

    Agent Runtime

    A multi-round ReAct loop prepares history, recalls relevant memories, calls the local model, executes approved tools, handles failures, and streams the final response.

  4. 04

    Tools and Safety

    Forge supports filesystem operations, shell commands, Git workflows, tests, patches, research, project retrieval, plans, sub-agents, security tools, skills, and MCP servers. Mutations are controlled by deterministic approval gates rather than relying only on model instructions.

  5. 05

    Local Models and Persistence

    Ollama runs local chat, coding, embedding, and vision models. SQLite stores sessions and episodes, while LanceDB stores semantic memory and project-scoped retrieval indexes.

Architecture

Forge separates interface, routing, tool execution, memory, and local model serving so each layer can evolve independently while remaining inspectable.

Core Capabilities

Local Model Orchestration

Runs open-weight coding, chat, embedding, and vision models locally through Ollama.

Structured Tool Execution

Allows models to read and edit files, run commands and tests, use Git, search the web, inspect images, update plans, and call MCP tools.

Route-Aware Behavior

Separates social conversation, local project analysis, research, and development tasks so each receives an appropriate prompt and tool allowlist.

Human-in-the-Loop Safety

Manual mode previews commands and changes before execution. Plan mode denies mutations. Security and elevated operations require stronger approval.

Project RAG

Indexes project files into LanceDB and retrieves relevant code based on semantic similarity.

Persistent Memory

Stores named sessions and conversation episodes in SQLite while keeping semantic facts in a separate vector memory layer.

Context Engineering

Prunes stale tool output, compacts long histories into structured summaries, preserves recent turns, and reserves context space for generation.

MCP Extensibility

Connects external Model Context Protocol servers and exposes their tools to the agent dynamically.

Sub-agents

Delegates repository exploration and security analysis to isolated agents without flooding the primary context.

Optional Model Specialization

Supports an MLX LoRA path for adapting compatible models to personal coding conventions on Apple Silicon.

Key Engineering Decisions

Use Ollama's native chat endpoint for tool turns.

Rationale: Some OpenAI-compatible Ollama endpoints may return Qwen tool calls as malformed XML or omit structured tool-call fields. Native Ollama chat provides more reliable tool behavior, while the OpenAI-compatible endpoint remains useful for non-tool requests.

Enforce safety outside the model prompt.

Rationale: Manual, automatic, planning, and ask modes are enforced by application code. File mutations, shell commands, Git operations, sudo, and security tools have deterministic gates that cannot be bypassed through persuasive prompting alone.

Separate sessions from episodes.

Rationale: A session represents a named long-term conversation bucket. Episodes represent isolated conversation segments so previous context does not silently bleed into every new launch.

Separate semantic memory from project RAG.

Rationale: Personal facts and reusable preferences have different retrieval and lifecycle requirements from indexed source-code chunks. Forge stores them in separate LanceDB collections.

Route turns before exposing tools.

Rationale: Social turns receive no tools, local questions receive read-oriented project tools, research receives web tools, and development tasks receive the full approved capability set. This reduces irrelevant tool calls and limits the model's action surface.

Delay streamed prose during potential tool calls.

Rationale: Forge holds initial response deltas until it knows whether the model is making a tool call. This prevents the interface from printing a conversational preamble and then duplicating the real answer after tool execution.

Use structured compaction instead of blind truncation.

Rationale: When context grows too large, Forge preserves intent, files, decisions, facts, and unresolved tasks instead of simply dropping the oldest messages.

Isolate banter from coding history.

Rationale: Social turns use a separate no-tool prompt and a scrubbed history view so expressive responses do not contaminate later technical work.

Safety Model

These controls reduce risk for local agent workflows. They are not a claim of complete security or impossibility of bypass.

Manual

Shows command or diff previews and requires approval before mutations.

Auto

Approves ordinary development mutations while retaining restrictions on elevated and security-sensitive actions.

Plan

Read-only. Mutating tools are denied regardless of what the model requests.

Ask

Pushes the agent toward clarification before taking action.

  • Shell denylist for destructive commands
  • Separate authorization for security and penetration-testing tools
  • RAM-only sudo credential handling
  • Optional Docker sandboxing
  • File checkpoints and undo
  • Repeated-tool loop detection
  • Tool-output size limits
  • Pre-commit secret scanning with gitleaks

Memory and Retrieval

SQLite Sessions

Stores session, timestamp, role, message content, and episode identifiers.

Semantic Memory

Uses nomic-embed-text and LanceDB to recall relevant long-term facts.

Project RAG

Indexes code and documentation in overlapping chunks scoped to the current project root.

Automatic Indexing

Projects are indexed automatically when they contain recognizable project markers. Very large repositories require an explicit indexing command.

Context Compaction

Preserves recent messages while converting older context into a structured summary when the token budget is exceeded.

End-to-End Agent Flow

  1. 01User enters a request in the terminal interface.
  2. 02Forge detects language and classifies the turn.
  3. 03The route selects tools, skills, and research behavior.
  4. 04Forge prepares history and recalls relevant semantic memory.
  5. 05The local model generates text or structured tool calls.
  6. 06Forge evaluates tool permissions and approval requirements.
  7. 07Approved tools execute and return bounded results.
  8. 08The agent repeats until the task is complete or the round limit is reached.
  9. 09The final answer streams into the interface.
  10. 10The episode is stored unless private mode is enabled.

Technical Highlights

  • Python 3.13+
  • Maximum 12 main-agent tool rounds
  • Maximum 8 read-only sub-agent rounds
  • Maximum 12 security-audit rounds
  • Four execution modes
  • Four route categories
  • SQLite session persistence
  • LanceDB semantic memory and project RAG
  • MCP tool integration
  • Local embedding and vision support
  • Optional MLX LoRA workflow
  • Tool-result limits and repeated-call detection
  • Automatic project indexing with large-repository safeguards

Technology

Runtime

  • Python 3.13
  • Typer

Interface

  • prompt_toolkit
  • Rich

Models

  • Ollama
  • Qwen3 Coder
  • Qwen2.5-VL
  • nomic-embed-text

Persistence

  • SQLite
  • LanceDB

Agent Infrastructure

  • Structured tool calling
  • ReAct loop
  • MCP
  • Skills
  • Sub-agents

Apple Silicon ML

  • MLX
  • mlx-lm
  • Optional LoRA adapters

Developer Operations

  • Git
  • Docker sandboxing
  • gitleaks
  • Automated tests

Current Status

Forge is an active independent engineering project currently at version 0.1.0. The production repository remains private because it contains personal development workflows, security tooling, local configuration conventions, and experimental agent infrastructure.

A public case study, architecture documentation, screenshots, and demonstrations are provided instead of unrestricted source-code access.

Public Release Vision

Goal: make Forge a free, open developer agent powered by the user's own local models.

Forge is being developed for public release as a local-first coding agent. Users bring an open-weight model that fits their hardware, while Forge provides the surrounding agent runtime: repository understanding, structured tools, reusable skills, memory, safety controls, and development workflows.

Core inference runs locally through Ollama, so Forge does not require a cloud-model subscription for everyday use. Developers remain in control of their source code, model selection, data, and compute environment.

Forge can inspect codebases, edit files, run commands and tests, manage Git workflows, retrieve project context through RAG, maintain session memory, and connect to external tools through MCP. Human approval gates remain available for file changes, commands, and other sensitive actions.

The long-term direction is simple: a capable developer agent that runs on your machine, works with the model you choose, and remains free to use.

Next Steps

Planned work — not yet completed features.

  • Ship a 60–90 second demo: repository inspection → plan → file edit → approval gate → tests → summary
  • Build a repeatable agent evaluation suite
  • Measure tool-call success and task-completion rates
  • Compare workflows with and without project RAG
  • Improve broad repository exploration through skim_codebase
  • Add more granular checkpoint persistence
  • Expand MCP compatibility and diagnostics
  • Improve local-model fallback and capability detection
  • Benchmark cold-start and warmed-model latency
  • Package a free public CLI distribution of the agent runtime