{"id":34559929,"url":"https://github.com/13shivam/park","last_synced_at":"2026-04-07T08:01:53.155Z","repository":{"id":328232081,"uuid":"1114644702","full_name":"13shivam/park","owner":"13shivam","description":"PARK: parallel agent runtime for kiro-cli, a multi-terminal launcher for managing Kiro CLI sessions. Launch, monitor, and control multiple AI agent sessions with real-time output streaming, session persistence, and batch operations. Built with Electron + TypeScript.","archived":false,"fork":false,"pushed_at":"2025-12-31T22:10:56.000Z","size":7016,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-05T10:18:55.072Z","etag":null,"topics":["ai-agents","amazonq","aws","brew","electron","electronjs","kiro","kiro-cli","kiro-dev","macos","multi-terminal","process-manager","pty","sqlite","terminal-emulator","typescipt","typescript","xterm-js"],"latest_commit_sha":null,"homepage":"https://github.com/13shivam/park/releases","language":"TypeScript","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/13shivam.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-11T17:09:17.000Z","updated_at":"2025-12-31T22:09:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/13shivam/park","commit_stats":null,"previous_names":["13shivam/park"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/13shivam/park","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/13shivam%2Fpark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/13shivam%2Fpark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/13shivam%2Fpark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/13shivam%2Fpark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/13shivam","download_url":"https://codeload.github.com/13shivam/park/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/13shivam%2Fpark/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31504897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["ai-agents","amazonq","aws","brew","electron","electronjs","kiro","kiro-cli","kiro-dev","macos","multi-terminal","process-manager","pty","sqlite","terminal-emulator","typescipt","typescript","xterm-js"],"created_at":"2025-12-24T08:52:52.863Z","updated_at":"2026-04-07T08:01:53.138Z","avatar_url":"https://github.com/13shivam.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PARK - Parallel Agent Runtime for Kiro\n\nA desktop application with a multi-terminal dashboard for managing and monitoring Kiro CLI sessions with support for both interactive and non-interactive modes.\n\n![Demo](diagrams/PARK_demo.gif)\n\n## Prerequisites\n\n⚠️ **IMPORTANT**: Before using PARK, you must have:\n- **Kiro CLI** installed and configured on your system\n- **Kiro CLI authenticated** and logged in (run `kiro-cli configure` if needed)\n- Verify by running `kiro-cli --version` in your terminal\n\nPARK launches Kiro CLI sessions - it does not include or install Kiro CLI itself.\n\n## Overview\n\nPARK is packaged as an Electron desktop app that provides:\n- Native desktop application for macOS (with Windows/Linux support planned)\n- Multi-terminal dashboard for managing Kiro CLI sessions\n- Launch and manage multiple Kiro CLI sessions simultaneously\n- Save session configurations for reuse\n- Monitor session status in real-time\n- View terminal output in an integrated interface\n- Support both interactive chat and non-interactive command execution\n\n## Architecture\n\n### High-Level Architecture\n\n![High-Level Design](diagrams/PARK_HLD.png)\n\n**Component Layers:**\n\n1. **Presentation Layer (Browser)**\n   - **UI Components**\n     - SessionList: Session rendering\n     - NewSessionModal: Modal dialogs\n     - EventHandlers: User interactions\n   - **Terminal Emulator** (xterm.js)\n   - **Theme Management** (Light/Dark)\n   - **WebSocket Client**\n\n2. **Frontend Business Logic**\n   - **SessionManager**: Session state \u0026 operations\n   - **TerminalManager**: Terminal lifecycle\n   - **CommandBuilder**: Command construction\n   - **PromptLoader**: Template loading\n\n3. **Application Layer (Backend)**\n   - Express HTTP Server\n   - WebSocket Server\n   - REST API Endpoints\n   - File Upload Handler\n\n4. **Backend Business Logic**\n   - Session Manager (Core logic)\n   - PTY Process Management\n   - Spawn Process Management\n   - Client Connection Multiplexing\n\n5. **Data Layer**\n   - SQLite Database (Session persistence)\n   - File System (Config, Uploads, Logs)\n\n6. **Process Layer**\n   - Kiro CLI PTY Processes (Interactive)\n   - Kiro CLI Spawn Processes (Non-interactive)\n\n### Class Structure\n\n**Key Classes:**\n\n**Frontend:**\n- **SessionManager**: Session state \u0026 operations (frontend)\n- **TerminalManager**: Terminal lifecycle management\n- **TerminalInstance**: xterm.js terminal emulator wrapper\n- **CommandBuilder**: Kiro CLI command construction\n- **PromptLoader**: Template loading utility\n\n**Backend:**\n- **SessionManager**: Core business logic for session lifecycle (backend)\n- **PTYInstance**: Wrapper for node-pty with client connections\n- **ProcessInstance**: Wrapper for child_process\n- **Database**: SQLite operations layer\n\n### Data Flow\n\n### Session Lifecycle\n\n![Session Lifecycle](diagrams/PARK_State_SessionLifecycle.png)\n\n**States:**\n- **Configured**: Saved config, not running (Gray dot, checkbox visible)\n- **Active**: Process running with PID (Green dot, no checkbox)\n- **Stopped**: Process killed/crashed (Red dot, checkbox visible)\n- **Completed**: Process exited normally (Orange dot, checkbox visible)\n\n**Transitions:**\n- Save Config → Configured\n- Launch/Rerun → Active\n- Stop/Crash → Stopped\n- Exit Normally → Completed\n- Delete → Removed from DB\n\n## Installation\n\n### macOS (Homebrew) - Recommended\n\n```bash\nbrew tap 13shivam/park\nbrew install --cask park\n```\n\nOr download the latest DMG from [Releases](https://github.com/13shivam/park/releases).\n\n### From Source\n\n```bash\n# Clone repository\ngit clone https://github.com/13shivam/park.git\ncd park\n\n# Install all dependencies\nnpm run install:all\n\n# Build and run in development\nnpm run dev\n```\n\n### Building Distributable\n\n```bash\n# Build for macOS\nnpm run package:mac\n\n# Output: dist/PARK-1.0.0.dmg\n```\n\n## Usage\n\n### Creating a Session\n\n1. Click the **+** button in the sidebar\n2. Select mode:\n   - **Interactive Chat**: Launch Kiro CLI in interactive mode\n   - **Non-Interactive Command**: Run a command and exit\n3. Configure:\n   - Session name\n   - Working directory\n   - Optional: Initial prompt (interactive) or file upload (non-interactive)\n4. Choose action:\n   - **Launch Now**: Start immediately\n   - **Save Config**: Save for later\n\n### Managing Sessions\n\n**Session Status Indicators:**\n- 🟢 Green: Active (running)\n- 🔴 Red: Stopped (killed/crashed)\n- 🟠 Orange: Completed (exited normally)\n- ⚫ Gray: Configured (not launched)\n\n**Actions:**\n- **Checkbox**: Select up to 5 non-active sessions\n- **Launch/Rerun Selected**: Launch configured or rerun stopped sessions\n- **↻ Button**: Rerun individual stopped/completed session\n- **Clean Up**: Delete all inactive sessions\n\n### Terminal View\n\n- Click active session to view in terminal\n- **Red dot (●)**: Stop the session (kills process)\n- **X**: Close terminal view (session keeps running)\n- **+**: Launch new session from empty state\n\n### Theme Toggle\n\n- Click **☀/🌙** button in sidebar header\n- Switches between light and dark themes\n- Preference saved in browser localStorage\n\n## Configuration\n\nConfiguration stored in: `~/.park-agent-launcher/config/config.json`\n\n```json\n{\n  \"server\": {\n    \"port\": 3000,\n    \"host\": \"localhost\"\n  },\n  \"shell\": {\n    \"defaultShell\": \"/bin/bash\",\n    \"defaultCwd\": \"~\"\n  },\n  \"ui\": {\n    \"defaultLayout\": \"1x1\",\n    \"theme\": \"dark\"\n  }\n}\n```\n\n## Database Schema\n\nSQLite database: `~/.park-agent-launcher/config/park.db`\n\n**Sessions Table:**\n```sql\nCREATE TABLE sessions (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  directory TEXT NOT NULL,\n  command TEXT NOT NULL,\n  status TEXT CHECK(status IN ('active', 'configured', 'stopped', 'completed')),\n  type TEXT CHECK(type IN ('interactive-pty', 'non-interactive')),\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  pid INTEGER\n);\n```\n\n## API Reference\n\n### Sessions API\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/sessions` | List all sessions |\n| GET | `/api/sessions/:id` | Get session details |\n| POST | `/api/sessions` | Create and launch session |\n| POST | `/api/sessions/config` | Save session config (don't launch) |\n| POST | `/api/sessions/launch` | Launch multiple sessions by ID |\n| POST | `/api/sessions/:id/stop` | Stop running session |\n| DELETE | `/api/sessions/:id` | Delete session |\n| DELETE | `/api/sessions` | Clean up all inactive sessions |\n\n### System API\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/system/config` | Get application configuration |\n| GET | `/api/system/prompts` | Get prompt templates |\n| POST | `/api/system/upload` | Upload file (returns path) |\n| GET | `/api/system/file-content?path=...` | Read uploaded file content |\n\n### WebSocket\n\n**Endpoint:** `ws://localhost:3000/terminal/:sessionId`\n\n**Client → Server Messages:**\n```json\n{\"type\": \"input\", \"data\": \"command\\n\"}\n{\"type\": \"resize\", \"cols\": 80, \"rows\": 30}\n```\n\n**Server → Client Messages:**\n```json\n{\"type\": \"output\", \"data\": \"terminal output\"}\n{\"type\": \"exit\", \"code\": 0}\n{\"type\": \"error\", \"message\": \"error description\"}\n{\"type\": \"history\", \"data\": \"buffered output\"}\n```\n\n## Features\n\n✅ Multi-session management  \n✅ Interactive and non-interactive modes  \n✅ Real-time terminal output streaming  \n✅ Session persistence across restarts  \n✅ Batch launch/rerun (up to 5 sessions)  \n✅ Light/dark theme toggle  \n✅ File upload for prompts  \n✅ Session status tracking with visual indicators  \n✅ Automatic cleanup of inactive sessions  \n✅ Terminal output buffering (1000 lines)  \n✅ WebSocket reconnection support  \n✅ Process lifecycle management  \n\n## Development\n\n### Backend\n```bash\nnpm run dev    # Development with auto-reload\nnpm run build  # Build TypeScript\nnpm start      # Production\n```\n\n### Frontend\n```bash\nnpm run dev      # Development server with HMR\nnpm run build    # Production build\nnpm run preview  # Preview production build\n```\n\n## Technical Details\n\n### Session Types\n\n**Interactive PTY (`interactive-pty`):**\n- Uses `node-pty` to spawn pseudo-terminal\n- Full terminal emulation with ANSI escape codes\n- Supports terminal resize\n- Bidirectional I/O streaming\n- Use case: `kiro-cli chat` interactive sessions\n\n**Non-Interactive Process (`non-interactive`):**\n- Uses Node.js `child_process.spawn`\n- Captures stdout/stderr\n- No terminal emulation\n- Use case: `kiro-cli chat --no-interactive` with prompt file\n\n### Performance Characteristics\n\n- **Session Creation**: ~100ms (PTY spawn time)\n- **WebSocket Latency**: \u003c10ms (local)\n- **Database Operations**: \u003c5ms (SQLite)\n- **Concurrent Sessions**: 50-100 (system resource dependent)\n- **Output Buffer**: 1000 lines per session\n- **Max Selected Sessions**: 5 (for batch operations)\n\n### Security Considerations\n\n1. **File System Access**: Limited to configured directories\n2. **Process Isolation**: Each session runs in separate process\n3. **WebSocket Validation**: Session ID checked before attachment\n4. **File Upload Limits**: 10MB max file size\n5. **Path Validation**: Uploaded files restricted to uploads directory\n\n## Troubleshooting\n\n**Backend won't start:**\n- Check if port 3000 is available\n- Verify Node.js version (18+)\n- Check `~/.park-agent-launcher/` directory permissions\n\n**Frontend can't connect:**\n- Ensure backend is running on port 3000\n- Check browser console for errors\n- Verify WebSocket connection in Network tab\n\n**Session shows as stopped but process is running:**\n- Backend was restarted while session was active\n- PID tracking lost - rerun the session\n\n**Terminal not displaying output:**\n- Check WebSocket connection status\n- Verify session is in 'active' state\n- Check backend logs for errors\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\nCopyright (c) 2025 https://github.com/13shivam\n\n## Trademarks \u0026 Attribution\n\n- **Kiro CLI** is a trademark of Amazon Web Services, Inc.\n- **AWS** and related marks are trademarks of Amazon Web Services, Inc.\n- All trademarks are the property of their respective owners.\n\nThis is an independent open-source project and is not officially affiliated with or endorsed by AWS.\n\n## Contributing\n\nContributions are welcome! To contribute:\n\n1. Fork the repository at [github.com/13shivam/park](https://github.com/13shivam/park)\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Test thoroughly\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## Support\n\nFor issues and questions:\n- **GitHub Issues**: [github.com/13shivam/park/issues](https://github.com/13shivam/park/issues)\n- **Maintainer**: https://github.com/13shivam\n- **Documentation**: See this README and architecture diagrams\n\n## Release Process\n\nReleases are automatically built and published via GitHub Actions when a version tag is pushed:\n\n```bash\ngit tag v1.0.0\ngit push origin v1.0.0\n```\n\nThis will:\n1. Build architecture-specific DMGs (arm64 and x64) for macOS\n2. Create a GitHub release with the DMG files\n3. Generate release notes automatically\n4. Automatically update the [homebrew-park](https://github.com/13shivam/homebrew-park) tap with new version and SHA256 checksums\n\nUsers can install the latest version via: `brew tap 13shivam/park \u0026\u0026 brew install --cask park`\n\nDownload the latest release from [Releases](https://github.com/13shivam/park/releases).\n\n### Homebrew Tap Setup\n\nThe Homebrew Cask formula is maintained in a separate repository: [homebrew-park](https://github.com/13shivam/homebrew-park)\n\nA template cask file is provided in `homebrew-cask-template.rb` for reference.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F13shivam%2Fpark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F13shivam%2Fpark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F13shivam%2Fpark/lists"}