https://github.com/roycoding8/recursia
Algorithmic context manager and execution engine for multi-agent workflows. Reduces TTFT and isolates attention by routing the minimal topological R/W subset to parallel LLMs.
https://github.com/roycoding8/recursia
agentic-workflows agents context-management llm ttft-optimization
Last synced: about 2 months ago
JSON representation
Algorithmic context manager and execution engine for multi-agent workflows. Reduces TTFT and isolates attention by routing the minimal topological R/W subset to parallel LLMs.
- Host: GitHub
- URL: https://github.com/roycoding8/recursia
- Owner: RoyCoding8
- License: apache-2.0
- Created: 2026-04-08T16:23:59.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-08T17:51:34.000Z (about 2 months ago)
- Last Synced: 2026-04-08T18:34:17.837Z (about 2 months ago)
- Topics: agentic-workflows, agents, context-management, llm, ttft-optimization
- Language: Python
- Homepage:
- Size: 337 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Recursia
Recursia is a recursive orchestration system for turning a single objective into a structured execution tree, evaluating intermediate results, and surfacing the full run in a live graph UI.
The project is split into a FastAPI backend and a Next.js frontend. The backend handles run lifecycle, recursive execution, persona routing, checker evaluation, merge flow, and event streaming. The frontend provides Mission Control for starting runs, inspecting node state, reviewing proposed files, and applying approved changes into a user-selected folder.
## Highlights
- Recursive divide-route-execute workflow
- Persona-based execution with markdown-backed persona profiles
- Live run graph and event console
- Proposal-based file generation instead of opaque server-side writes
- Review-and-apply workflow for writing approved files into a selected folder
- Separate validation feedback for checker verdicts versus real runtime failures
## Repository Layout
- `backend/` FastAPI API, orchestration runtime, state management, and tests
- `frontend/` Next.js Mission Control UI and component/E2E tests
- `personas/` markdown persona profiles discovered at runtime
- `theory/` product and architecture notes
- `run.bat` Windows launcher for local setup and development
## Quick Start
### Launchers
Windows:
```powershell
.\run.bat
```
Linux and macOS:
```bash
bash ./run.sh
```
Both launchers can install dependencies, start the backend and frontend, and open the app in your browser when the environment supports it.
### Manual startup
Backend:
```powershell
cd backend
uv sync
uv run uvicorn main:app --reload
```
Frontend:
```powershell
cd frontend
npm ci
npm run dev
```
The frontend expects the backend at `http://127.0.0.1:8000` by default.
## Tooling
The backend is managed as a `uv` project and should be installed with `uv sync`. The frontend uses `npm` with the checked-in `package-lock.json` for deterministic installs.
## Personas
Persona profiles are loaded from `personas/*.md`. The frontend exposes these profiles as selectable base personas when starting a run. The selected base persona is applied to the root node, while downstream nodes may still route to other personas as needed.
## Development Notes
- Backend tests live under `backend/tests/`
- Frontend tests live under `frontend/tests/`
- Local generated artifacts are intentionally excluded from version control via `.gitignore`
## Continuous Integration
GitHub Actions runs basic checks on push and pull request across Windows, macOS, and Linux:
- backend `uv run pytest -q`
- frontend `npm run typecheck`
- frontend `npm run test:components`
## License
This project is released under the Apache License 2.0.