🤖 OpenThrottle | AI

OpenThrottle is an open-core, AI-native platform for planning and shipping software. At its core is a Postgres-backed knowledge base of plans and tasks with semantic search, exposed to your editor and agents over MCP, plus agentic execution (Ralph) and a developer dashboard that shows what's in progress and what shipped. The repo is an Nx + pnpm monorepo with TypeScript throughout.

⚙️ Installation

Setup is simple and scripted:

nvm use # or install the correct NodeJS version (see .nvmrc for the version to use)

./scripts/setup.sh

Then setup the MCP servers globally:

pnpm run setup:mcp-instructions

[!Tip]

You can run this setup script ANYTIME you need to reset your environment or resolve setup-related issues. See the Troubleshooting section below for common scenarios where running the setup script can help.

🚀 Get Started

OpenThrottle is a AI Harness built in a NX monorepo using NodeJS, TypeScript, PostgreSQL, Redis, NestJS, BullMQ, React Router and much more. The local stack (full walkthrough: local-quickstart.md)

1. Startup from the "openthrottle/monorepo" root

 pnpm run start

2. Watch the logs for the two applications to start up
3. http://localhost:6021 OpenThrottle Server 🧠
4. http://localhost:6020 OpenThrottle Developer 🏍️💨
5. Turn it off ~ if you can...

 pnpm run stop

🏠 Architecture

├── .env.default           # Default environment variables (in VC)
├── .agents
├── applications           # NodeJS client and server applications
├── databases              # Postgres schema, migrations, and local DB scripts
├── docs                   # Markdown documentation (see docs/)
├── infra                  # Infrastructure as code (e.g. GCP, Terraform)
├── packages               # Shared packages that can also be published
├── scripts                # Scripts to make life easier (Bash + TypeScript)
├── services               # Shared or standalone services
├── skills                 # Custom agent skills (Ralph, code review, generators, …)
└── tools                  # Nx plugins, templates, workflows (see tools/)

🚦 Project status

OpenThrottle is open core and built in the open. The table below sets expectations before you dive into any one app — everything here is Apache-2.0, but not everything is finished.

Application	Status	What it is
openthrottle	✅ Stable	Quick-start / product landing (the docker compose up entrypoint).
openthrottle-server	✅ Stable	NestJS code-first GraphQL API — the backbone of the platform.
openthrottle-developer	✅ Stable	The flagship developer portal: plans, projects, notes, generators.
openthrottle-website	✅ Stable	Marketing site.
openthrottle-admin	🧭 Planned	Corporate management layer. On the roadmap; not production-ready.
openthrottle-workbench	🛠️ Internal	Storybook host for the shadcn component library. A dev tool, not a deployed app.

[!NOTE] 🧭 Planned and 🚧 Experimental apps ship as previews so you can see where OpenThrottle is headed. They build and pass CI, but aren't feature-complete — don't depend on them yet.

🛟 Troubleshooting

When issues arise, our goal is to provide straightforward solutions that allow you to quickly reset and restore your development environment to a working state.

1. Build Issues?

Sometimes you just want to start fresh, to do that:

# Stop anything that's running
pnpm run stop

# Nuke all the artifacts and node modules
pnpm run clean

# Re-install and build things
./scripts/setup.sh

2. Database Issues?

Try stopping and starting Postgres + Redis with the root pnpm scripts:

pnpm run database:stop
pnpm run database:start

See databases/README.md and local-quickstart.md.

3. Version mismatches?

To see what versions of a package are installed we can use pnpm list. From there we typically need to set a specific resolution in our package.json. e.g. pnpm list react

4. Other issues?

Open a GitHub issue with what you tried and the error output, and we'll help you get unstuck.

📄 License

OpenThrottle is open core: the core is licensed under the Apache License, Version 2.0 (see LICENSE.md), with commercial/enterprise modules reserved under a separate EULA. All current first-party code is Apache-2.0.

See LICENSING.md for the open-core boundary — which directories are Apache-2.0 vs EULA, and how to tell.

The code is open source, but the OpenThrottle name and logo are trademarks — Apache-2.0 §6 grants no trademark rights. See TRADEMARK.md for what you may and may not do with the marks.