# Forge > Forge is a local-first software engineering agent. It combines local models with repository understanding, structured tools, project retrieval, persistent memory, MCP extensions, and developer-controlled execution, adapting to the hardware and models available on your machine. **Category:** Local-First Software Engineering Agent **Headline:** Forge your codebase with an agent you control. **Status:** Active Development **Runtime:** Hardware-aware **Compatibility:** macOS first · broader support planned **Release:** Public Release Planned **Version:** 0.1.0 **Control modes:** manual · auto · plan · ask **Canonical:** https://destinyxstudios.com/projects/forge **Markdown:** https://destinyxstudios.com/projects/forge.md **Company:** https://destinyxstudios.com/ Bring your own model. Forge provides the agent runtime. Local inference by default. Cloud services only when explicitly enabled. The first public release targets macOS (Apple Silicon). Windows and Linux support will follow in a later release. ## Why Forge exists Cloud coding agents often combine the model, agent runtime, memory, tools, and subscription into one closed service. Forge separates those layers. The developer chooses the compatible models and compute environment. Forge provides repository context, structured tools, execution controls, memory, retrieval, recovery, and the workflow connecting them. This separation allows models to change without requiring the entire development environment to change with them. The model is one component. Forge is the system around it. ## Built for real repositories ### Project awareness Forge maps the repository, retrieves relevant files, preserves working context, and keeps project knowledge separate from personal semantic memory. ### Verification in the loop Changes are not treated as finished when text appears. Forge can run commands and tests, inspect failures, revise its work, and continue until the task is done or needs input. ### Recovery when things go wrong File checkpoints, undo, tool-output limits, and approval gates exist because agentic coding touches real files and shells — not because mistakes are theoretical. ### Extensible workflows Skills, MCP servers, and model profiles let developers shape Forge around their stack without rebuilding the agent loop each time. ## Work across the development lifecycle ### Understand a codebase Forge can map a repository, inspect its structure, search symbols and text, retrieve indexed context, and delegate deeper read-only exploration to sub-agents. ### Implement changes The agent can write and edit files, apply patches, follow a live plan, and make coordinated changes across multiple parts of a project. ### Run and verify Forge can execute commands, run tests, inspect failures, revise its work, and continue until the task is complete or requires user input. ### Work with Git The agent can inspect status and diffs, review history, manage branches, prepare commits, and push changes when authorized. ### Research when needed Research tasks can use web search and page retrieval, while local project questions remain focused on the workspace instead of reaching for the internet unnecessarily. ### Connect external tools MCP support allows Forge to use additional tools and services configured by the developer. ## Control without constant babysitting Forge separates agent capability from agent authority. ### Manual Preview commands and file changes before they run. Approve once, reject them, or trust an approved tool for the current session. ### Auto Allow routine development actions to proceed without repeated confirmation while retaining restrictions around elevated or security-sensitive operations. ### Plan Explore the repository and produce an implementation plan without permitting mutations. ### Ask Require the agent to clarify uncertain requirements before it begins acting. Autonomy is a setting, not a personality trait. ## An agent harness built for real development work Every request passes through a route-aware agent runtime. Forge determines whether the turn is social, local project work, research, or development work. The route controls which tools, context, skills, and workflows become available. For development tasks, Forge: 1. Prepares and compacts conversation context. 2. Recalls relevant project and semantic memory. 3. Sends the task and authorized tools to the selected model. 4. Evaluates requested actions against the active execution mode. 5. Runs approved tools and returns bounded results. 6. Repeats until the task is complete or the round limit is reached. 7. Streams the final response and saves the session unless private mode is active. The model proposes actions. The Forge runtime decides what is allowed to execute. ## Project context without dumping the entire repository Sending every file to a model is expensive, slow, and usually a terrible retrieval strategy disguised as confidence. Forge combines several context systems: ### Codebase mapping skim_codebase builds a structural view of the project before broad exploration begins. ### Project RAG Source code and documentation are indexed into a project-scoped LanceDB collection and retrieved by semantic relevance. ### Semantic memory Reusable facts and preferences are stored separately from project source material. ### Sessions and episodes Named sessions preserve long-term work, while isolated episodes prevent previous conversations from silently contaminating every new launch. ### Context compaction When a conversation approaches the model’s context limit, Forge preserves intent, files, decisions, facts, and open tasks instead of blindly deleting old messages. ## Built to act without pretending mistakes are impossible Agentic coding involves real file changes and shell access. Forge treats those capabilities as controlled operations rather than prompt suggestions. - Command and diff previews - Read-only planning mode - Destructive shell-command blocking - Separate approval for security tools - RAM-only sudo credentials - Optional Docker sandboxing - File checkpoints and undo - Repeated tool-call detection - Tool-output limits - Pre-commit secret scanning - Per-session trusted-tool controls Forge is designed to reduce the risk of agent actions while keeping the developer responsible for what ultimately runs. ## Hardware-aware model profiles Forge selects compatible model profiles and runtime settings based on the resources available on the machine. Coding, embedding, vision, and lightweight routing can use different models when the system supports them. Larger machines can run broader-context coding models with stronger multi-step tool use; smaller systems keep the same workflow with lighter profiles and correspondingly different speed and capability. Capability changes with hardware. The development loop does not. ## Memory with explicit boundaries Forge keeps different types of state separate. ### Session history SQLite stores conversation messages, timestamps, named sessions, and episode boundaries. ### Semantic memory LanceDB stores reusable facts and preferences that can be recalled when relevant. ### Project knowledge Repository chunks are indexed separately and scoped to their project root. ### Private mode Private sessions can run without being written to persistent conversation storage. This separation helps prevent a preference from becoming source-code context, or one repository from bleeding into another. ## Adapt Forge to how you build ### Skills Markdown playbooks can define repeatable workflows for coding, research, Git operations, interface review, security analysis, and project-specific conventions. ### MCP Model Context Protocol servers can expose external tools to Forge through a common interface. ### Model profiles Profiles define context size, inference settings, tool support, and hardware expectations for different local models. ### Optional specialization Forge includes an experimental specialization workflow for creating LoRA adapters from curated examples and running specialized models on supported hardware. ## Transparent network boundaries Sessions, semantic memory, and project indexes are stored on the machine by default. Data may leave the machine only when a networked capability is used explicitly — web search, remote page retrieval, Git push, external MCP servers, remote model endpoints, or other configured third-party services. Forge should surface when those tools are active rather than hiding the boundary behind a blanket privacy claim. Local where possible. Explicit when not. ## Active development Forge is currently at version 0.1.0 and remains under private development. ### Current implementation - Full-screen terminal interface - Route-aware agent loop - Filesystem, shell, Git, test, research, and planning tools - Manual, automatic, plan, and ask modes - SQLite sessions - LanceDB memory and project retrieval - Context compaction - Sub-agents - MCP support - Skills - Checkpoints and undo - Local model, embedding, and vision support - Optional MLX LoRA workflow ### Development priorities - Repeatable agent evaluations - More reliable broad-repository exploration - Stronger checkpoint persistence - Better model capability detection - Improved tool-call reliability - Public-safe documentation - Release packaging ## Public release direction Forge is being prepared for a future public release. The first release targets macOS on Apple Silicon. Windows and Linux follow once that build is stable enough for broader use. The intended direction is a free developer tool that can be run, inspected, extended, and adapted in the developer’s own environment — without a mandatory model subscription. Public packaging, docs, and installation details will ship when the system is ready. ## Forge is still being forged. Release details will be announced when Forge is ready for broader use.