Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.
The contract layer for agentic software development. ForgeOS turns application source into deterministic runtime contracts, generated clients, safety checks, and machine-readable context that humans and AI coding agents can use safely.
Status: private/public alpha MVP, implemented through H49. ForgeOS already includes the compiler, local runtime, frontend SDK, production auth, RLS compiler, liveQuery, self-host artifacts, generated agent contract, guided dev loop, repair/review/test tooling, AST-aware codemods, package intelligence, native AI tools/agents, DeltaDB work memory, external agent memory ingestion, brownfield import analysis, npm alpha publishing, and Read the Docs public docs. Public release hardening is still focused on deeper semantic codemods, broader field reports, and more production mileage.
Public docs live at forgeos.readthedocs.io. The repo builds them with .readthedocs.yaml, mkdocs.yml, and docs/index.md.
Start with Why ForgeOS to understand the agent-native design.
For the short version, read The Five-Minute ForgeOS Model, Alpha Golden Path, and Stable Alpha Surface. The important distinction is that external coding agents are the primary ForgeOS workflow; integrated AI SDK features are available for apps that need in-product AI, but they are not the main development loop.
bun install --ignore-scripts
bun run forge generate
bun run forge do inspect --json
bun run forge dev
bun run forge dev --once --json
bun run forge inspect all --json
bun run forge inspect framework --json
bun run forge doctor
bun run forge verify --standard
bun run forge verify --strict
Node is supported for the CLI/runtime path as well:
npm install
npm run forge:node -- generate
npm run forge:node -- dev --once --json
npm run forge:node -- inspect framework --json
When working as an AI coder, read:
AGENTS.md
src/forge/_generated/agentContract.json
src/forge/_generated/runtimeRules.md
src/forge/_generated/appMap.md
src/forge/_generated/operationPlaybooks.md
These files describe the app surface, runtime rules, generated files, policies, secrets, workflows, UI routes, commands to run, and common repair/refactor playbooks.
Public one-command app creation:
npm create forgeos-app@alpha notes-app -- --template minimal-web
cd notes-app
npm run dev
Equivalent lower-level command without installing ForgeOS globally:
npm exec --package forgeos@alpha -- forge new notes-app --template minimal-web --package-manager npm
If ForgeOS is already installed or you are inside this repository:
forge new notes-app --template minimal-web --package-manager npm
cd notes-app
npm run dev -- --open
forge dev starts the API runtime and the web dev server together when a web/ app exists. The --once --json mode is the central agent/CI diagnostic entrypoint: it checks generated drift, guardrails, frontend routes/bindings, doctor status, impact, and the last test/UI reports in one deterministic response.
Template apps ignore src/forge/_generated/, forge.lock, and operational .forge/** work dirs by default so a freshly created app does not flood git or the editor with generated files. Run forge generate after checkout or before verification to recreate the agent contract, client SDK, frontend graph, capability map, and runtime manifests.
Templates also include workspace editor excludes for generated/runtime directories so source files stay visually prominent.
For release or external smoke testing, choose the Forge package source explicitly:
forge new smoke-app --template minimal-web --package-manager npm --forge-spec "npm:forgeos@alpha"
forge new local-app --template minimal-web --package-manager npm --local-forge
--forge-spec writes that dependency spec into the generated app, while --local-forge keeps the monorepo/local package workflow. The npm package is published as forgeos, but generated apps keep the dependency key, CLI binary, and import surface as forge (forge, forge/server, forge/react) by using npm alias specs such as "forge": "npm:forgeos@alpha". CI uses both --forge-spec "file:$GITHUB_WORKSPACE" and a packed tarball smoke to prove freshly created apps can install ForgeOS and run outside the framework workspace.
For broader field testing:
npm run field:test -- --dry-run --json
npm run field:test -- --package-managers npm --templates minimal-web --forge-spec "file:." --install --json
The scheduled/manual Field Tests workflow expands that coverage across Linux, macOS, Windows, Node 22, Node 24, and npm/pnpm/yarn/bun.
ForgeOS can import services written outside TypeScript through the Forge Protocol.
External runtimes publish a forge.manifest.json that describes commands, queries,
transport, policies, risk metadata, tenant scope, and schemas. Forge then emits
the same machine-readable app/API/agent artifacts and exposes runtime bridge
endpoints for those entries.
The Go example starts a manifest-backed service:
cd examples/go-billing
go run . --manifest --base-url http://127.0.0.1:8787 > forge.manifest.json
go run . --addr 127.0.0.1:8787 --base-url http://127.0.0.1:8787
In a Forge app:
forge manifest validate ./forge.manifest.json --json
forge manifest import ./forge.manifest.json --json
forge generate
forge run billing.createInvoice --args '{"title":"Invoice"}' --user-id u1 --tenant-id tenant-a --role admin
forge query billing.listInvoices --args '{}' --user-id u1 --tenant-id tenant-a --role admin
For Java, see adapters/java,
adapters/java-spring-boot-starter,
and examples/java-billing.
See docs/forge-protocol.md, schemas/forge-manifest.schema.json,
and adapters/go.
src/forge/_generated/
api.ts/json
client.ts, clientTypes.ts, clientApi.ts
react.ts, reactManifest.ts/json
appGraph.ts/json
dataGraph.ts/json
runtimeGraph.ts/json
runtimeMatrix.ts/json
policyRegistry.ts/json
permissionMatrix.ts/json
tenantScope.ts/json
secretRegistry.ts/json
aiRegistry.ts/json
workflowRegistry.ts/json
liveQueryRegistry.ts/json
agentContract.ts/json
capabilityMap.ts/json/md
agentAdapterManifest.ts/json
testGraph.ts/json
uiTestManifest.ts/json
uiRoutes.ts/json
uiScenarios.ts/json
Project-level generated context:
AGENTS.md
forge.lock
.forge/test-plans/**
.forge/repairs/**
.forge/refactors/**
.forge/ui-runs/**
| Area | What exists now |
|---|---|
| Compiler | AppGraph, DataGraph, RuntimeGraph, PackageGraph, deterministic generated artifacts, drift checks |
| Runtime | commands, queries, liveQueries, actions, workflows, durable outbox, local dev server |
| Data | schema compiler, SQL DDL, migrations, PGlite/Postgres adapter, tenant scope metadata |
| Policies | RBAC policy registry, permission matrix, simulation, strict policy checks |
| Auth | dev headers, JWT, OIDC discovery/JWKS verification via jose, production-mode guardrails |
| RLS | Postgres RLS SQL compiler/checks for DB-enforced tenant isolation |
| Secrets/env | secret registry, env schema, redaction, strict process.env checks |
| AI | Vercel AI SDK v6 engine, provider registry, ctx.ai, ctx.agent.run, aiTool, agent, /ai/agents/run JSON automation, /ai/agents/chat UIMessage streaming, forge ai trace, structural and model-level redteam probes, mock mode, telemetry without prompt/output retention by default |
| Frontend | generated client SDK, React/Next hooks, template app, liveQuery client support |
| LiveQuery | durable invalidation log, reconnect/resume semantics, production hardening checks |
| DeltaDB | ambient local recorder plus inferred work sessions and semantic timelines for Forge commands, dev file saves, generated artifacts, runtime calls, policies, proofs, diagnostics, forge timeline, forge explain, and optional forge session correction |
| Agent memory | opt-in Codex and Claude Code hooks, Cursor MCP/rules setup, normalized external agent events, redacted local memory, and forge mcp serve |
| Brownfield import | static TypeScript/JavaScript app inventory with routes, frontend calls, env usage, candidate entries, risk report, migration plan, and hidden-by-default imported agent contract |
| Self-host | compose/deploy artifacts and self-host checks |
| Agent contract | AGENTS.md, agentContract.json, app maps, runtime rules, playbooks, inspect/doctor |
| Authoring | forge make, feature blueprints, safe refactor plans, package upgrade plans |
| Testing/repair | impact-based test planner, repair loop, structured review, UI/browser test bridge |
| Adapters | Forge Protocol manifest import plus Go, Java, and Spring Boot adapter support for executable external commands and queries |
| Intent router | forge do maps objectives like fix, verify, connect UI, and add feature into plans, files, risks, and next commands |
| Full-stack map | frontendGraph + capabilityMap connect routes, components, hooks, runtime entries, tables, policies, and gaps |
| Dev loop | forge dev prints API/Web URLs, phase health, capability coverage, cache status, diagnostics, and next action |
| Templates | source-only templates and showcase app avoid committing generated artifacts by default |
| Verification | forge verify --smoke, --standard, and --strict report per-step duration/command metadata, use impact-selected tests for the standard loop, and time out package scripts predictably |
Prefer task-oriented commands first:
forge do "<objective>" --json
forge do fix --json
forge do connect-ui --json
forge do verify --json
forge dev --once --json
forge dev
forge inspect all --json
forge inspect framework --json
forge inspect capabilities --json
forge delta status
forge timeline
forge timeline --session current
forge explain <thing>
forge explain session current
forge session list
forge agent memory --json
forge mcp serve
forge import analyze --json
forge inspect imported --json
forge doctor
forge verify --standard
forge verify --strict
forge impact --changed --json
forge test plan --changed --json
forge test run --changed --timeout-ms 120000 --json
forge repair diagnose --from-last-test-run --json
forge repair diagnose --from-last-ui-run --json
forge review run --changed --json
forge ui smoke --json
Common command groups:
| Command | Purpose |
|---|---|
forge generate | Analyze source and emit generated artifacts |
forge generate --check | Fail on generated drift |
forge check --json | Validate guardrails and emit diagnostics with fix hints |
forge verify --smoke | Fast local gate: generated drift, Forge checks, typecheck when present, no tests/lint |
forge verify --standard | Agent development gate: generated drift, Forge/security checks, typecheck, and impact-selected tests |
forge verify --strict | Full handoff/CI gate: generated drift, Forge/security checks, typecheck, full TestGraph in bounded parallel/isolated chunks, lint |
forge verify --script-timeout-ms <ms> | Run package scripts with a predictable timeout and machine-readable timeout diagnostics |
forge verify --test-jobs <n> | Tune strict TestGraph chunk parallelism; FORGE_VERIFY_TEST_JOBS is also supported |
forge verify --strict --test-plan --json | Print the strict TestGraph scheduler plan without running tests |
forge do "<objective>" --json | Guided intent router: choose the right workflow, files, risks, and next action |
forge inspect <target> --json | Inspect generated app/data/runtime/policy/client/agent/UI surfaces |
forge inspect framework --json | Inspect ForgeOS framework modules, CLI commands, templates, examples, tests, and preferred entrypoints |
forge doctor --json | Human/agent health check for project coherence |
forge dev | Interactive local loop: generated checks, API runtime, DB, worker, watch mode, frontend server, URLs, and next agent checks |
forge dev --once --json | One-shot diagnostic orchestrator for agents/CI: generated drift/cache hit, check, frontend, capability map, doctor, impact, reports, next actions |
forge run, forge query, forge live | Execute and inspect runtime entries locally |
forge db, forge rls | Diff/migrate/status and inspect/check RLS |
forge policy, forge secrets, forge env, forge auth | Security and configuration operations |
forge make | Scaffold resources, commands, queries, policies, actions, workflows |
forge feature | Validate/plan/apply feature blueprints |
forge refactor | Plan/apply/rollback safe refactors and targeted codemods |
forge impact, forge test | Compute change impact and run targeted checks |
forge test run --timeout-ms <ms> | Run impact-selected checks with a per-command timeout |
forge repair | Diagnose failures and produce repair plans |
forge review | Structured code review with findings and suggested commands |
forge ui | Browser/UI smoke, scenario, route, snapshot, doctor, and reports |
forge deps | Package upgrade planning and application |
forge release | Release/source-map bridge and symbolication |
forge agent, forge agent-contract | Agent-facing contract, adapter exports, context, install, ingest, and memory commands |
forge mcp serve | MCP server for external agents to read Forge context, memory, timeline, and inspect surfaces |
forge import analyze, forge import inspect | Brownfield TypeScript/JavaScript app inventory and reviewed migration planning |
forge inspect imported --json | Inspect .forge/import analysis artifacts |
forge self-host | Self-host packaging and checks |
Refactor codemods are AST-aware where safety matters most:
forge refactor extract-action is binding-aware and preserves unrelated imports, type-only imports, and shadowed locals.forge refactor rename command <oldName> <newName> rewrites command declarations, generated client references, React hook usage, tests, and safe string references while preserving unrelated symbols.forge refactor rename field <table.field> <table.field> rewrites structured TS/JS/JSX/TSX and JSON references, preserves locals, and scopes the field change to files/objects linked to the target table. For example, tickets.priority -> tickets.urgency does not rewrite a generic priority prop in a component with no tickets binding.forge refactor rename table <from> <to> rewrites table definitions, ctx.db.<table> access, policy strings, JSON/blueprints, and import/export specifiers while preserving unrelated locals with the same name.Commands are transactional and deterministic:
ctx.db, ctx.emit, buffered telemetryctx.secrets, ctx.ai, direct process.envQueries and liveQueries are read-only:
Actions and workflows handle side effects after commit:
Use src/forge/_generated/runtimeRules.md as the canonical generated version.
See examples/showcase-forge-app.
cd examples/showcase-forge-app
npm install
npm run generate
npm run dev
For the reproducible public proof path:
npm run proof:inspect
npm run proof:dev
npm run proof:capabilities
npm run proof:verify
Read examples/showcase-forge-app/PUBLIC_PROOF.md for the full walkthrough.
Examples are source-only where practical: generated artifacts, forge.lock, package lockfiles, and operational .forge/** state are recreated locally. The showcase demonstrates tenant-scoped data, policies, commands, queries, liveQueries, outbox actions, workflows, mock AI, telemetry trace IDs, generated React hooks, agentContract, frontendGraph, capabilityMap, and the standard agent handoff loop.
| Platform | Support |
|---|---|
| Linux | Supported for MVP development |
| macOS | Supported for MVP development |
| Windows (WSL) | Supported for MVP development |
| Windows (native) | Experimental, with forge doctor windows and forge setup windows |
ForgeOS is Bun-first but no longer Bun-only. The package bin runs through Node via tsx, the dev server has a node:http fallback, package scripts use the detected package manager, and the Postgres adapter uses Bun.SQL when available or the postgres npm package under Node.
Known Windows note: ForgeOS resolves Bun through a Windows-safe resolver and ignores known non-Bun Kiro-Cli\bun shims. If your shell still resolves a broken app association, invoke Bun from the real install path:
& "$env:USERPROFILE\.bun\bin\bun.exe"
Native Windows diagnostics:
node .\bin\forge.mjs doctor windows --json
node .\bin\forge.mjs setup windows --json
forge doctor windows checks Node, npm, Git, safe Bun resolution, suspicious Bun shims, Git long-path support, PowerShell execution policy, and symlink support. forge setup windows is dry-run by default and only applies supported environment fixes with --yes.
For Node-only local checks, use:
node .\bin\forge.mjs dev --once --json
node .\bin\forge.mjs inspect framework --json
Fast focused checks:
bun run typecheck
bun run lint
bun test tests/<area>
bun run forge generate --check
forge verify --changed
Full gate:
bun test --timeout 120000
bun run forge verify --strict
UI bridge note: forge ui uses Playwright when installed. Without Playwright, forge ui doctor --json reports FORGE_UI_PLAYWRIGHT_MISSING with fix hints instead of silently failing.
Frontend bridge note: forge inspect frontend --json and forge dev --once --json expose routes, components, ForgeProvider, generated client bindings, raw runtime fetch warnings, and fix hints. Agents should use this before editing UI wiring.
CI note: the main GitHub Actions gate runs the full Bun-based verification path on Ubuntu. A separate Node breadth smoke matrix runs on Ubuntu, Windows, and macOS with Node 22 and 24, including template package-manager smoke for npm, pnpm, yarn, and Bun.
ForgeOS publishes to npm as forgeos and exposes the executable as forge.
Release automation uses Changesets plus npm Trusted Publishing:
npm run changeset
npm run version-packages
npm run release:smoke
For the first prerelease publish, use the alpha dist-tag explicitly:
npm run release:publish-local-alpha -- --dry-run
npm run release:publish-alpha
The normal path is:
merge feature PR with changeset
-> publish.yml opens/updates a version PR
merge version PR
-> publish.yml publishes through npm OIDC Trusted Publisher
Configure npm Trusted Publisher for package forgeos:
| Field | Value |
|---|---|
| Provider | GitHub Actions |
| Organization/user | Stahldavid |
| Repository | forge |
| Workflow filename | publish.yml |
| Environment | blank |
| Allowed action | npm publish |
Do not add NPM_TOKEN for normal alpha publishes. Alpha releases publish with the alpha dist-tag through npm OIDC Trusted Publisher so prerelease builds do not become latest accidentally. Configure NPM_TOKEN only when maintainers intentionally want the workflow to promote latest with npm dist-tag add forgeos@<version> latest; otherwise that step is skipped and latest may lag behind alpha during hardening. Use release:publish-local-alpha -- --dry-run only to validate the staged tarball locally; real npm publishing should go through release:publish-alpha, which dispatches publish.yml and uses npm OIDC Trusted Publisher. The workflow checks whether the package version already exists before installing dependencies or running tests, then uses id-token: write, Node 24/npm 11+, and provenance for the actual publish. npm run release:smoke runs npm pack, creates a fresh app with the packed tarball, installs dependencies, runs forge dev --once --json, and verifies the app smoke path.
H1 Hardening, CI, examples
H2 Reference integration quality
H3 DataGraph Compiler
H4 Local command/action runtime
H5 Local dev server
H6 DataGraph-backed persistence runtime
H7 Durable outbox worker
H8 Lightweight workflow engine
H9 Telemetry bridge
H10 Auth, policy engine, tenant isolation
H11 Secrets & environment runtime
H12 AI workflow integration
H13 Query runtime & typed API surface
H14 Frontend client SDK core
H15 LiveQuery/Reactivity MVP
H16 React/Next hooks
H17 Minimal frontend app template
H18 Self-host packaging
H19 Agent Contract & Project Introspection Layer
H20 Production Auth / JWT & OIDC v1
H21 Postgres RLS Compiler & DB-enforced tenant isolation
H22 Package Upgrade Planner
H23 Release / Source Map Bridge
H24 Production LiveQuery Hardening
H25 Authoring primitives: forge make
H26 Feature Blueprint Compiler
H27 Safe Refactor / Codemod Engine
H28 Impact-Based Test Planner
H29 Repair Loop
H30 Agent Adapter Export
H31 Forge Review / Structured Code Review
H32 UI / Browser Test Bridge
H33 Intent Router / Guided Dev Loop
H34 Full-Stack App Contract v2
H35 Capability Map
H36 Template hygiene / git noise
H37 Convex-style forge dev panel
H38 Fast generated check visibility
H39 Showcase app
H40 Windows/runtime hardening
H41 Node-compatible CLI/runtime
H42 Verify observability and quieter app workspaces
H43 Native AI tools and agent loop
H44 Ambient DeltaDB recorder
H45 Automatic work-session inference
H46 Automatic change grouping
H47 Semantic timeline
H48 Agent Memory Bridge
H49 Brownfield import analysis
extract-action, rename command, rename field, and rename table paths.FAQs
Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.
We found that forgeos demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
GitHub Actions now supports cache-mode, a least-privilege control on the Actions cache aimed at the cache poisoning technique behind recent compromises.
Company News
Allow myself to introduce... myself.
Research
/Security News
A Twitch browser extension on Chrome and Firefox forwards users’ live OAuth session tokens through proxies controlled by a Russian bot service.