Local-First Software Engineering Agent
✻ Welcome to Forge!
Forge your codebase with an agent you control.
Forge maps your repository, edits code, runs commands and tests, manages Git workflows, retrieves project context, and connects to external tools.
Its runtime adapts to the models and hardware available on your machine.
The first public release targets macOS (Apple Silicon). Windows and Linux support will follow in a later release.
Bring your own model. Forge provides the agent runtime.
Local inference by default. Cloud services only when explicitly enabled.
~/forge/intro
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.
~/forge/values
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.
~/forge/capabilities
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.
~/forge/modes
Control without constant babysitting
Forge separates agent capability from agent authority.
Preview commands and file changes before they run. Approve once, reject them, or trust an approved tool for the current session.
Allow routine development actions to proceed without repeated confirmation while retaining restrictions around elevated or security-sensitive operations.
Explore the repository and produce an implementation plan without permitting mutations.
Require the agent to clarify uncertain requirements before it begins acting.
Autonomy is a setting, not a personality trait.
~/forge/runtime
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:
- 01Prepares and compacts conversation context.
- 02Recalls relevant project and semantic memory.
- 03Sends the task and authorized tools to the selected model.
- 04Evaluates requested actions against the active execution mode.
- 05Runs approved tools and returns bounded results.
- 06Repeats until the task is complete or the round limit is reached.
- 07Streams 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.
~/forge/context
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.
~/forge/safety
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.
~/forge/models
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.
~/forge/memory
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.
~/forge/extensibility
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.
~/forge/privacy
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.
~/forge/status
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
~/forge/release
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/next
Forge is still being forged.
Release details will be announced when Forge is ready for broader use.
forge · local software engineering agent · destinyx studios · forge.md · llms.txt