{"id":34638836,"url":"https://github.com/darth-dodo/pocket-portals","last_synced_at":"2026-04-14T00:32:02.013Z","repository":{"id":329733315,"uuid":"1120488008","full_name":"darth-dodo/pocket-portals","owner":"darth-dodo","description":"🎒 Pocket Portals is a web application that generates personalized one-shot text-based RPG adventures using multi-agent AI. ","archived":false,"fork":false,"pushed_at":"2026-01-10T18:06:13.000Z","size":7283,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T03:19:02.212Z","etag":null,"topics":["crewai","crewai-agents","dnd","fastapi","python3"],"latest_commit_sha":null,"homepage":"https://pocket-portals.onrender.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/darth-dodo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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":null,"dco":null,"cla":null}},"created_at":"2025-12-21T10:26:47.000Z","updated_at":"2026-01-10T10:18:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/darth-dodo/pocket-portals","commit_stats":null,"previous_names":["darth-dodo/pocket-portals"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/darth-dodo/pocket-portals","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darth-dodo%2Fpocket-portals","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darth-dodo%2Fpocket-portals/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darth-dodo%2Fpocket-portals/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darth-dodo%2Fpocket-portals/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/darth-dodo","download_url":"https://codeload.github.com/darth-dodo/pocket-portals/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darth-dodo%2Fpocket-portals/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31776925,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T00:11:49.126Z","status":"ssl_error","status_checked_at":"2026-04-14T00:10:29.837Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["crewai","crewai-agents","dnd","fastapi","python3"],"created_at":"2025-12-24T17:13:27.130Z","updated_at":"2026-04-14T00:32:02.002Z","avatar_url":"https://github.com/darth-dodo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pocket Portals\n\n\u003e **Your character. Your choices. Your adventure.**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-3.12-blue?logo=python\" alt=\"Python 3.12\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Tests-859_passing-brightgreen?logo=pytest\" alt=\"Tests: 859 passing\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Coverage-77%25-green?logo=codecov\" alt=\"Coverage: 77%\"\u003e\n\u003c/p\u003e\n\n---\n\nA solo D\u0026D adventure game powered by AI agents. Create your character, choose your quest, and shape your own story through an interactive text-based RPG experience.\n\nNo group needed. No scheduling. Just you and the portal.\n\n---\n\n## Meet the Innkeeper\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/e2e-screenshots/02-quest-started.png\" alt=\"Innkeeper Welcome\" width=\"400\"\u003e\n\u003c/p\u003e\n\nStep through the portal into a weathered tavern. The **Innkeeper** greets you with knowing eyes:\n\n\u003e *\"Well now, another soul seeking adventure. Before I point you toward trouble, tell me — who are you, traveler?\"*\n\nAnswer his questions, build your character, and choose from personalized quests tailored to your abilities.\n\n---\n\n## How It Works\n\n### 1. Create Your Character\nA 5-turn conversation builds your hero — class, background, motivations, and equipment. No forms, just storytelling.\n\n### 2. Choose Your Quest\nThree personalized adventures await. Rogues get stealth missions. Paladins get protection quests. Your character shapes your options.\n\n### 3. Shape Your Story\nExplore, fight, negotiate, flee. Every choice matters. The narrative adapts to your decisions.\n\n### 4. Roll the Dice\nReal D\u0026D 5e mechanics. Initiative, attack rolls, HP tracking. Combat is deterministic — no AI randomness.\n\n---\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **7 AI Agents** | Narrator, Keeper, Jester, Innkeeper, Interviewer, QuestDesigner, Epilogue |\n| **Quest Selection** | 3 personalized quests based on your character |\n| **D\u0026D 5e Combat** | Real dice mechanics, initiative, HP tracking |\n| **50-Turn Arcs** | Paced adventures with setup, climax, and resolution |\n| **5 Themes** | RPG, Modern, Midnight, Mono, iOS Dark |\n| **Mobile-First** | Haptic feedback, touch targets, responsive design |\n\n---\n\n## Screenshots\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/e2e-screenshots/09-quest-selection.png\" alt=\"Quest Selection\" width=\"280\"\u003e\n  \u003cimg src=\"docs/e2e-screenshots/10-exploration-after-quest-selection.png\" alt=\"Exploration\" width=\"280\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eChoose Your Quest • Explore the World\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n## Quick Start\n\n```bash\ngit clone https://github.com/darth-dodo/pocket-portals.git\ncd pocket-portals\n\ncp .env.example .env\n# Add your ANTHROPIC_API_KEY\n\nmake install\nmake dev\n# Visit http://localhost:8888\n```\n\n---\n\n## For Developers\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTech Stack \u0026 Architecture\u003c/strong\u003e\u003c/summary\u003e\n\n### Tech Stack\n\n| Component | Technology |\n|-----------|------------|\n| **Runtime** | Python 3.12 |\n| **API** | FastAPI with SSE streaming (modular architecture) |\n| **AI** | CrewAI + Anthropic Claude |\n| **Frontend** | Vanilla JS + Modern CSS |\n| **State** | CrewAI Flow with persistence (InMemory/Redis) |\n| **Security** | Rate limiting + configurable CORS |\n\n### Codebase Health\n\n| Metric | Value |\n|--------|-------|\n| **Python Tests** | 500+ passing |\n| **JS Tests** | 415 passing |\n| **Coverage** | 77% |\n| **Type Checking** | Strict mypy |\n| **Linting** | Ruff + pre-commit |\n| **Rate Limiting** | Privacy-first (session_id only) |\n\n### Architecture\n\n```mermaid\nflowchart LR\n    Player[Player Action] --\u003e Router[Agent Router]\n    Router --\u003e Agents[AI Agents]\n    Agents --\u003e Claude[Claude 3.5 Haiku]\n    Agents --\u003e Story[Narrative + Choices]\n    Story --\u003e Player\n```\n\n### AI Agents\n\n- **Narrator** — Scene descriptions with phase-aware pacing\n- **Keeper** — D\u0026D 5e rules and dice mechanics\n- **Jester** — Chaos injection (15% chance per turn)\n- **Innkeeper** — Quest hooks and rumors\n- **Interviewer** — Character creation interview\n- **QuestDesigner** — Personalized quest generation\n- **Epilogue** — Adventure conclusions\n\n### Documentation\n\n- [Architecture](docs/architecture.md) — System design\n- [Quest System](docs/design/quest-system.md) — Quest generation \u0026 selection\n- [Onboarding](docs/guides/ONBOARDING.md) — Developer setup\n- [E2E Testing](docs/playwright-e2e-suite.md) — Playwright test scenarios\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDevelopment Commands\u003c/strong\u003e\u003c/summary\u003e\n\n| Command | Description |\n|---------|-------------|\n| `make install` | Install dependencies |\n| `make dev` | Start dev server |\n| `make test` | Run Python tests |\n| `npm test` | Run JS tests |\n| `make lint` | Code quality checks |\n\n\u003c/details\u003e\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eBuilt with\u003c/strong\u003e\u003cbr/\u003e\n  \u003ca href=\"https://crewai.com\"\u003eCrewAI\u003c/a\u003e •\n  \u003ca href=\"https://anthropic.com\"\u003eAnthropic Claude\u003c/a\u003e •\n  \u003ca href=\"https://fastapi.tiangolo.com\"\u003eFastAPI\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eStep through the portal. Begin your quest.\u003c/em\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarth-dodo%2Fpocket-portals","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarth-dodo%2Fpocket-portals","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarth-dodo%2Fpocket-portals/lists"}