Plan visually. Track delivery. Share your plan through Git.
StateForge DPT (Development Progress Tracking) is a local web app for planning and tracking work across GitHub repositories. Create steps, connect dependencies, and see what is ready to build next—all in a visual workspace.
Your plan lives alongside your code in Git. Issues, pull requests, and merges provide the delivery evidence. Each computer keeps its own local working copy.
- Visual planning. Describe a result, choose a repository, and select prerequisite cards. DPT handles step IDs, ordering, and dependency validation.
- A connected roadmap. Explore dependency stages or a graph, with search and repository filters.
- An actionable work queue. See ready, pending, in-review, blocked, and completed work, with assigned contributors and their profile photos.
- GitHub context in one place. Read formatted descriptions, comments, reviews, and activity. Open issues, create planned branches and PRs, or jump to GitHub to start a review. The dashboard also shows each repository's latest successful GitHub Actions run on the plan source branch.
- Commit-specific vulnerability evidence. Generate a CycloneDX inventory from the exact plan-source commit, assess dependencies with OSV, and join the result with exact-head CodeQL evidence. Missing or incomplete coverage is shown honestly instead of being presented as a clean result.
- Git-backed collaboration. Share the complete plan in
STATEFORGE_DPT.mdand import it on another computer from a participating clone. - Continuous safe synchronization. DPT keeps the shared plan, delivery evidence, and CI status current in the background after GitHub is connected, without switching branches. Refreshes are adaptive, concurrent, and coalesced across the server and every open tab; conflicts and unpublished local edits are surfaced, not overwritten. Routine refreshes compare a lightweight GitHub index and fully reload only changed evidence, with periodic full audits as a correctness backstop.
- Regression-resistant implementation. Define cross-repository context, protected behavior, and verification before work begins; review the exact change surface and retain relevant bug history afterward.
- Cross-repository implementation integrity. Map protocol contracts to the Provider and Agent symbols that implement or consume them. A merged milestone makes DPT visibly stale until its exact PR is reviewed, the graph is updated or explicitly marked unaffected, and the next plan revision is published.
- A first-class AI interface. The same local process exposes DPT through MCP, so coding agents can inspect roadmaps, blockers, repository context, and implementation packages without scraping the browser. Agents may propose plan edits, but an exact digest-bound proposal needs human confirmation.
Requires Python 3.11+ and Git 2.31+ on your PATH. Runs on Linux, macOS, and Windows. The browser interface is included; Node.js is not needed.
python -m pip install stateforge-dpt
stateforge-dpt runOpen http://127.0.0.1:8463 in your browser. Start DPT
from any directory, keep the terminal open, and press Ctrl+C to stop it.
On macOS/Linux, use python3 if needed. On Windows, use
py -m pip install stateforge-dpt and py -m stateforge_dpt run if the
console command is not on your PATH.
Use a virtual environment for an OS-managed Python. If you already use
pipx, pipx install stateforge-dpt is another option.
- Connect GitHub—or start locally. Choose Continue with GitHub and approve the one-time code. Local mode supports planning without signing in; refreshing GitHub delivery evidence requires a connected account.
- Add repositories. Create a project, then attach existing clones or choose Clone for me.
- Build the plan. In Plan editor, create a step, describe its expected result, and choose its repository. Select prerequisite cards to connect work across repositories—no dependency IDs to memorize.
- Follow delivery. Explore Roadmap and Work queue. DPT refreshes every project's shared plan and GitHub evidence automatically while the DPT server is running; Sync now remains available when you want an immediate refresh.
Joining an existing project? Choose Import from repository on the projects
page and select a local clone containing a published STATEFORGE_DPT.md.
DPT previews the complete plan before importing it.
stateforge-dpt run also serves a local Streamable HTTP MCP endpoint:
http://127.0.0.1:8463/mcp
For the Codex desktop app, install DPT's personal local plugin once:
stateforge-dpt setup-codexThen keep DPT running, restart the Codex app, and start a new chat. The setup
command preserves other personal marketplace entries, registers the loopback
MCP endpoint, and configures proposal application and rejection to prompt for
confirmation in Codex. Rerun it after changing DPT's configured port, or pass
the matching endpoint with --url.
Connect an MCP-capable coding client to that URL while DPT is running. The agent can read projects, dependency stages, the work queue, GitHub blockers, managed repository trees, approved context contracts, and implementation packages. File access is limited to Git-tracked text resources in attached repositories and bounded by a configurable read limit.
Discovery tools intentionally return compact milestone and blocker cards.
Agents call get_work_item only for the selected item's complete GitHub,
context, and review evidence, keeping routine planning queries small.
Plan editing uses a proposal boundary. The agent submits typed operations; DPT
validates the complete resulting plan and returns an immutable review package
with a semantic diff, consequences, version, and SHA-256 review digest. After
you review it in the conversation, the agent may call the consequential apply
tool. Keep per-call tool confirmation enabled in your MCP client—never
auto-approve apply_plan_change_proposal. The same proposals can be inspected,
applied, or rejected in Plan editor → AI proposals.
Applying a proposal changes only the local SQLite working plan. It never writes
STATEFORGE_DPT.md, publishes a revision, commits, pushes, opens a pull request,
reviews, or merges. Those remain separate human-owned workflows. Run with
--no-mcp to disable the agent interface. See the
AI agent interface guide
for the complete tool and safety model.
Collaborate through your repositories, not a separate planning server:
- Configure the StateForge DPT GitHub App publisher as described in Configuration.
- Choose Review & publish in Plan editor to preview the next revision. After confirmation, DPT creates a GitHub-verified App commit containing only the generated plan file and advances the project's protected plan source branch directly.
- On another computer, install DPT and import the project from any participating clone. Attach or clone the remaining repositories; the steps and dependencies are already there.
- Connect GitHub. DPT automatically fetches newer plan revisions and delivery evidence—even while you remain on a feature branch.
The source branch can be your default branch or another shared parent, such as
mvp/implementation. Only Review & publish uses the App installation
identity and its ruleset bypass. Issues, pull requests, reviews, reconciliation,
and every other GitHub operation remain attributed to the connected user.
Publishing and reconciliation do not rebase or change the active working
tree. Conflicting revisions or unpublished local edits require your resolution.
DPT uses project, release, and step labels to match GitHub activity to the plan:
| Matched GitHub evidence | DPT state |
|---|---|
| Open issue | Pending |
| Open pull request | In review |
| Merged pull request | Completed |
| Closed, unmerged pull request | Cancelled |
Without matched evidence, prerequisites determine whether work is ready or blocked. Reconciliation flags workflow findings, such as a PR opened before its dependencies are complete. Perform reviews on GitHub using the shortcut to the PR's Files changed tab.
Working copies, cached GitHub activity, and encrypted credentials live under
~/.stateforge-dpt/. New clones default to:
~/.stateforge-dpt/projects/<PROJECT_NAME>/<REPOSITORY_NAME>
The shared plan excludes credentials, cached conversations, and local clone paths. Each collaborator uses their own account and clones. Remote cloning, shared-plan fetching, and GitHub updates require network access.
Update DPT with:
python -m pip install --upgrade stateforge-dptDPT is an early-stage release. Keep generated plan changes in Git for review and recovery through your normal development workflow.
- Configuration and troubleshooting
- Architecture and plan format
- Vulnerability evidence and SBOM cache
- AI regression-resistance workflow
- AI agent interface
- Development and release guide
- Issue tracker
GitHub documentation and the issue tracker require access to the project repository.