{"id":47072145,"url":"https://github.com/toddmedema/opensprint","last_synced_at":"2026-04-04T00:05:29.069Z","repository":{"id":339121035,"uuid":"1158297876","full_name":"toddmedema/opensprint","owner":"toddmedema","description":"Plan and build at the speed of thought.","archived":false,"fork":false,"pushed_at":"2026-04-01T22:47:21.000Z","size":11973,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T04:54:33.017Z","etag":null,"topics":["ai-agents","orchestration","product-management"],"latest_commit_sha":null,"homepage":"http://opensprint.ai/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toddmedema.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-15T05:42:51.000Z","updated_at":"2026-04-01T22:47:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/toddmedema/opensprint","commit_stats":null,"previous_names":["toddmedema/opensprint.dev","toddmedema/opensprint.ai"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/toddmedema/opensprint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toddmedema%2Fopensprint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toddmedema%2Fopensprint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toddmedema%2Fopensprint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toddmedema%2Fopensprint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toddmedema","download_url":"https://codeload.github.com/toddmedema/opensprint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toddmedema%2Fopensprint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31382355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T23:20:52.058Z","status":"ssl_error","status_checked_at":"2026-04-03T23:20:51.675Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","orchestration","product-management"],"created_at":"2026-03-12T06:05:44.932Z","updated_at":"2026-04-04T00:05:29.049Z","avatar_url":"https://github.com/toddmedema.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Open Sprint\n\n[Open Sprint](https://opensprint.ai/) is an AI-powered software development lifecycle platform that guides a project from idea to shipped code across Sketch, Plan, Execute, Evaluate, and Deliver.\n\n## Quick Start\n\nFor the fastest start, Electron app downloads are available on the [releases page](https://github.com/toddmedema/opensprint/releases).\n\n### Mac/Linux\n\nPrerequisites:\n\n- [Git](https://git-scm.com/install/)\n- [Node.js 24.x](https://nodejs.org/en/download)\n- Git identity configured:\n  - `git config --global user.name \"Your Name\"`\n  - `git config --global user.email \"you@example.com\"`\n\n```bash\ngit clone https://github.com/toddmedema/opensprint.git\ncd opensprint\nnpm run setup\nnpm run dev\n```\n\nThen open [http://localhost:5173](http://localhost:5173).\n\nOptional faster source setup (skips Electron/Puppeteer workspace installs): `OPENSPRINT_SETUP_MINIMAL=1 npm run setup`\n\n### Windows\n\nYou will need to install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) with Node.js: open PowerShell as admin, run `wsl --install`, reboot, then open the WSL application and [install Node.js 24.x](https://nodejs.org/en/download). Open Sprint uses SQLite by default in WSL; for PostgreSQL, install it in WSL and set `databaseUrl` in Settings.\n\nThen, from the default ~ directory, run:\n\n```bash\ngit clone https://github.com/toddmedema/opensprint.git\ncd opensprint\nnpm run setup\nnpm run dev\n```\n\nOptional faster source setup (skips Electron/Puppeteer workspace installs): `OPENSPRINT_SETUP_MINIMAL=1 npm run setup`\n\n_Native Windows Node, PowerShell, and `cmd.exe` execution are unsupported because the orchestration and process-management stack assumes Linux/Unix process behavior. Do not run Open Sprint from `/mnt/c/...` or any other Windows-mounted filesystem._\n\n### Database\n\nOpen Sprint uses **SQLite by default** and stores data at `~/.opensprint/data/opensprint.sqlite`.\nFor first run, **no additional database setup is required**.\n\nIf you need **higher performance** and **cross-team collaboration**, you can optionally point Open Sprint to a PostgreSQL database:\n\n- In the app: **Settings** -\u003e set `databaseUrl` or use **Upgrade to PostgreSQL**\n- In config: set `databaseUrl` in `~/.opensprint/global-settings.json`\n- In env: set `DATABASE_URL` (highest precedence)\n\n#### Upgrading to PostgreSQL\n\nUse this only if SQLite no longer meets your needs (for example, larger workloads or multi-user collaboration).\n\n1. **In the app:** Open **Settings**, use **Upgrade to PostgreSQL** to enter your Postgres URL, migrate data, and switch in one step.\n2. **Manually:** Set `databaseUrl` in `~/.opensprint/global-settings.json` to your PostgreSQL URL (for example, `postgresql://user:password@localhost:5432/opensprint`), run **Set up tables** in Settings if needed, then restart the app.\n\nTo install and prepare a local PostgreSQL during setup, run `USE_POSTGRES=1 npm run setup`.\n\n### Integration token encryption\n\nThe backend encrypts stored integration OAuth tokens (for example Todoist) at rest. By default it uses a key derived from this machine’s hostname and a per-install salt in `~/.opensprint/encryption-salt`. That is fine for casual single-user local use.\n\n**On shared servers, multi-user hosts, or any environment where another OS user could read `~/.opensprint`, you must set `INTEGRATION_ENCRYPTION_KEY` in the environment** before starting the backend. Use a **base64-encoded 32-byte** cryptographically random key, for example:\n\n```bash\nopenssl rand -base64 32\n```\n\nPut the value in `.env` at the repo root or in your process manager’s environment. If the variable is unset, the backend logs a startup warning reminding you to set it for sensitive deployments.\n\n### PostgreSQL Setup FAQ\n\nOnly needed if you are using PostgreSQL.\n\n- If you already have PostgreSQL running, Open Sprint expects a local role `opensprint` with password `opensprint` and a local database named `opensprint`.\n- If automatic setup cannot create the role or database, create them manually and rerun `USE_POSTGRES=1 npm run setup`.\n- If another PostgreSQL install is already using the default port or conflicts with setup, use that existing local install and create the expected role and database yourself, or update the database URL in Settings to point to a different database.\n\n## How Open Sprint Works\n\nOpen Sprint uses the SPEED Product Management lifecycle:\n\n- **Sketch**: turn an idea into a clear product spec\n- **Plan**: break the spec into epics, tasks, and dependencies\n- **Execute**: AI agents implement the work\n- **Evaluate**: review results and feed changes back into planning\n- **Deliver**: ship working software\n\nSpecialized agents handle planning, implementation, review, and handoff so the project keeps moving without manual orchestration at every step.\n\n## Architecture at a Glance\n\nOpen Sprint is a monorepo with four main packages:\n\n- `packages/backend`: Node.js + TypeScript API and orchestrator\n- `packages/frontend`: React + TypeScript web app\n- `packages/shared`: shared types and constants\n- `packages/electron`: Electron desktop shell (spawns backend, serves frontend in one window)\n\nThe product spec for Open Sprint lives in `SPEC.md`. Each project's Sketch output is also written to `SPEC.md` at that project repo root.\n\n## Common Commands\n\n| Command                                    | What it does                                                                                                   |\n| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |\n| `npm run setup`                            | Install dependencies, create default SQLite DB, and apply schema (optional: `USE_POSTGRES=1`)                  |\n| `OPENSPRINT_SETUP_MINIMAL=1 npm run setup` | Install only shared/backend/frontend deps for source development (skips Electron/Puppeteer workspace installs) |\n| `npm run dev`                              | Start the backend and frontend                                                                                 |\n| `npm run test`                             | Run the test suite                                                                                             |\n| `npm run lint`                             | Run lint checks across workspaces                                                                              |\n| `npm run build`                            | Build all packages                                                                                             |\n| `npm run start:desktop`                    | Run the Electron desktop app (builds once, then opens a window)                                                |\n| `npm run build:desktop`                    | Build installers (for example, `.dmg`, `.exe`, `AppImage`) to `packages/electron/dist/`                        |\n\n## Troubleshooting\n\n### \"The coding agent stopped without reporting whether the task succeeded or failed.\" (no_result)\n\nThis means the **coding agent process** (for example, Cursor CLI) exited before writing `.opensprint/active/\u003ctaskId\u003e/result.json`. The orchestrator only considers a run successful when it can read that file, so if the process crashes or exits early, you get `no_result`.\n\n**Typical causes:**\n\n1. **API or auth**: Cursor/API key missing, invalid, or rate-limited. The agent may exit with code 1 as soon as it tries to call the API.\n2. **Model config**: wrong or unsupported model name. Some backends return errors like \"not a chat model\" and the CLI exits 1.\n3. **Process crash**: the agent CLI crashes before the model responds.\n\n**What to do:**\n\n- In **Settings**, check the AI provider and model. For Cursor, ensure the Cursor agent CLI is installed and `CURSOR_API_KEY` (or your key source) is set.\n- For the failing task, open the **agent output log** at `.opensprint/active/\u003ctaskId\u003e/agent-output.log` under the project worktree path (for example, `opensprint-worktrees/\u003ctaskId\u003e/`).\n- If you see API or auth errors, fix the key/model and retry. The task will be requeued; after repeated failures it may be blocked to prevent looped failures.\n\n## Contributing\n\nSee **[CONTRIBUTING.md](CONTRIBUTING.md)** for setup, quality checks, submitting pull requests, and the two-clone workflow when developing on this repo with Open Sprint.\n\n## Building the Desktop App\n\nYou can run Open Sprint as a desktop app (Electron) or build installable artifacts.\n\n**Prerequisites:** Same as Quick Start (Node.js 24.x). The desktop app uses SQLite by default; config and data live in `~/.opensprint` (see [Database](#database) and [PostgreSQL Setup FAQ](#postgresql-setup-faq)). For macOS installer builds, Apple's appearance-aware app icon pipeline now goes through `actool`, so use full Xcode 26 or newer instead of Command Line Tools alone.\n\n**Linux runtime prerequisites (Electron):** Install common desktop libs before running `npm run start:desktop` or launching the Linux AppImage (for example on Ubuntu/Debian: `sudo apt-get install -y libgtk-3-0 libnss3 libasound2 libxss1 libxtst6 libatspi2.0-0 libsecret-1-0 libnotify4 libcups2 libgbm1`).  \nFor AppImage specifically, install FUSE2 (`libfuse2`) or AppImage may fail to launch.\n\n- **Run desktop in development:** From the repo root, run `npm run start:desktop`. This builds the app once, then launches Electron. The window loads the backend-served UI at `http://127.0.0.1:3100`. Only one instance runs; relaunching focuses the existing window. On macOS, if you see \"Electron quit unexpectedly\" during startup, the script runs a fix automatically; see [docs/macos-desktop-signing.md](docs/macos-desktop-signing.md#macos-development-electron-quit-unexpectedly) for details.\n- **Build installers:** Run `npm run build:desktop`. This builds shared, backend, and frontend, prepares a self-contained backend and frontend in `packages/electron/desktop-resources/`, then runs electron-builder. Output goes to `packages/electron/dist/` (for example, `.dmg` on macOS, `.exe` installer on Windows, `AppImage` on Linux). The packaged app runs the backend with Electron's embedded Node runtime.\n\n## Publishing Desktop Releases\n\nPushing a version tag (for example, `v1.0.0`) triggers GitHub Actions to build the Electron app for macOS (DMG), Windows (installer `.exe`), and Linux (AppImage), and to attach those files to the GitHub Release for that tag. The workflow sets the app version from the tag so the built installers show the correct version.\n\nmacOS releases are signed with a `Developer ID Application` certificate and notarized in GitHub Actions before the DMG is uploaded. Setup details for the certificate export, App Store Connect API key, required GitHub secrets, CI verification commands, and the temporary workaround for older unsigned DMGs are in [docs/macos-desktop-signing.md](docs/macos-desktop-signing.md).\n\n## License\n\n[AGPL-3.0](LICENSE). Support or partnership: [contact@opensprint.ai](mailto:contact@opensprint.ai).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoddmedema%2Fopensprint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoddmedema%2Fopensprint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoddmedema%2Fopensprint/lists"}