agent-coral 2.0.0__tar.gz

agent_coral-2.0.0/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: agent-coral
+Version: 2.0.0
+Summary: A multi-agent orchestration system for managing AI coding agents (Claude and Gemini) in parallel git worktrees with a real-time web dashboard.
+Author: Chris Knorowski
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cdknorow/coral
+Project-URL: Repository, https://github.com/cdknorow/coral
+Project-URL: Issues, https://github.com/cdknorow/coral/issues
+Keywords: ai,agents,claude,gemini,orchestration,tmux,multi-agent,coding-agents,dashboard
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn[standard]>=0.24.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: python-multipart>=0.0.6
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+
+<img width="1024" height="250" alt="image" src="https://github.com/user-attachments/assets/8b7b1467-ecba-4b63-9151-137f2d2243ec" />
+
+---
+
+## The Pitch
+
+Coral brings sanity to coding with AI agents without disrupting your workflow. The goal is to augment, not take over. Activity across all your agents is visible so you can see which ones need attention at a glance.
+
+Stop losing track of what your AI coding agents are doing. As you scale your workflow, the chaos of scattered terminals, lost context, and untracked changes slows you down. Coral is the mission control center you need to effortlessly orchestrate your entire AI workforce. Maintain total visibility over every agent's progress, organize your history, and automate routine tasks so you can focus on building. Stop fighting your tools and start multiplying your productivity—with all your data completely secure and private on your own machine.
+
+Coral is an MIT-licensed multi-agent orchestration application built with tmux, FastAPI, and vanilla HTML5/JS for easy extensibility and modification. We welcome feedback and contributions.
+
+**[Read the full documentation →](https://cdknorow.github.io/coral/)**
+
+
+![main_loop](https://github.com/user-attachments/assets/6af60c92-1d72-45bd-9b46-7f1eab2ce5fe)
+
+## Features
+
+- **Multi-agent support** — Launch and manage both Claude and Gemini agents side-by-side across worktrees
+- **Web dashboard** — Real-time monitoring with pane capture, status tracking, and command input
+- **Session history** — Browse past sessions with advanced filters (date range, agent type, tags, full-text search)
+- **Full-text search** — Search across all session content using SQLite FTS5 with porter stemming
+- **Auto-summarization** — Sessions are automatically summarized and indexed for search
+- **Scheduled jobs** — Create cron-scheduled tasks that launch agents in isolated worktrees, send prompts, and clean up automatically
+- **Webhook notifications** — Get notified via webhook when agents need input or complete work
+- **Session notes & activity** — Add markdown notes and track activity that occurred in each session, live and historically
+- **Remote control** — Send commands, navigate modes, and manage agents from the dashboard
+- **Attach/Kill/Restart/Resume** — Open a terminal attached to any agent's tmux session, kill it, or relaunch as a new session
+- **Git integration & PR linking** — Tracks commits, branches, and remote URLs per agent and session
+- **Custom macros** — Add configurable toolbar buttons for frequently used commands
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install agent-coral
+```
+
+Or install directly from GitHub:
+
+```bash
+pip install git+https://github.com/cdknorow/coral.git
+```
+
+## Launch agents and web dashboard
+
+You can launch the web server directly using `coral` or `coral-dashboard`:
+
+```bash
+# Start the web dashboard directly (default: http://localhost:8420)
+coral
+
+# Custom host/port
+coral --host 127.0.0.1 --port 9000
+
+```
+
+> **Note:** This system is currently mostly tested with Claude Code and to some extent Gemini CLI. However, the underlying architecture is extensible to any cli based agents.
+
+### Session history search and filtering
+
+![history](https://github.com/user-attachments/assets/3848aefe-e358-425b-ae14-ed2f41704a33)
+
+
+The sidebar History section includes a search bar and filters for browsing your entire AI coding session history along with activity, notes, and git commit tracking
+
+On startup, the server launches three background services:
+
+1. **Session indexer** (every 2 min) — Indexes all Claude sessions from `~/.claude/projects/**/*.jsonl` and Gemini sessions from `~/.gemini/tmp/*/chats/session-*.json`, builds a full-text search index (FTS5), and queues new sessions for auto-summarization
+2. **Batch summarizer** — Continuously processes the summarization queue using Claude CLI
+3. **Git poller** (every 2 min) — Polls git branch, commit, and remote URL for each live agent and stores snapshots in SQLite
+
+Features:
+
+- **Search** — Type in the search bar to find sessions by content (uses SQLite FTS5 with porter stemming)
+- **Filter by tag** — Select a tag from the dropdown to narrow results
+- **Filter by source** — Show only Claude or Gemini sessions
+- **Filter by date** — Narrow results to a specific date range
+- **Pagination** — Browse through all sessions with prev/next controls
+- **URL bookmarking** — Session URLs use hash routing (`#session/<id>`) so you can bookmark or share links
+- **Notes & tags** — Add markdown notes and color-coded tags to any session, stored in `~/.coral/sessions.db`
+
+
+### Managing sessions from the dashboard
+
+<img width="1502" height="812" alt="image" src="https://github.com/user-attachments/assets/9a8d1b7b-1bef-414b-9002-c27dd928342b" />
+
+
+The web dashboard provides quick-action buttons for each live session:
+
+| Action | Description |
+|---|---|
+| **Esc / Arrow / Enter** | Send navigation keys to the agent |
+| **Plan Mode** | Toggle Claude Code plan mode |
+| **Accept Edits** | Toggle Claude Code auto-accept mode |
+| **Bash Mode** | Send `!` command to enter bash mode |
+| **Base Mode** | Toggle base mode |
+| **/compact / /clear** | Send compress or clear commands (adapts per agent type) |
+| **Reset** | Compress then clear the session |
+| **Attach** | Open a local terminal window attached to the agent's tmux session |
+| **Restart** | Restart the agent in the same tmux pane |
+| **Kill** | Terminate the tmux session and remove it from the dashboard |
+
+You can also type arbitrary commands in the input bar and send them to the selected agent.
+
+
+
+### Scheduled Jobs
+
+Coral supports cron-scheduled jobs that automatically launch agents in isolated git worktrees. Create and manage them from the Scheduled section in the sidebar.
+
+Each scheduled job:
+- Creates a fresh git worktree from the specified branch
+- Launches an agent (Claude or Gemini) with optional CLI flags
+- Sends the configured prompt to the agent
+- Monitors the session with a configurable timeout
+- Cleans up the worktree on completion (optional)
+- Tags the session as "scheduled" for easy filtering in history
+
+Run history is tracked per job with links to view each session's full history.
+
+### Webhook Notifications
+
+Configure webhooks from the dashboard settings to receive HTTP notifications when agents need input or when other events occur. Useful for integrating with Slack, Discord, or custom monitoring.
+
+### Claude Code Hooks (settings.json)
+
+To fully integrate Claude Code's agentic state and task management into the Coral dashboard, configure the provided `coral-hook` scripts in your Claude Code `settings.json` (usually located at `~/.claude.json` or `~/.claude/settings.json`).
+
+If you are already using other configuration options like a custom `statusLine` or other hooks, simply merge these hook definitions into your existing JSON:
+
+```json
+"hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "TaskCreate|TaskUpdate",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "coral-hook-task-sync"
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "coral-hook-agentic-state"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "coral-hook-agentic-state"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "coral-hook-agentic-state"
+          }
+        ]
+      }
+    ]
+
+```
+
+
+
+Or use launcher which discovers worktree subdirectories, creates a agent for each one, and starts launches the dashboard:
+
+```bash
+# Launch Claude agents and web dashboard for worktrees in the current directory
+launch-coral
+
+# Launch Gemini agents from a specific path
+launch-coral <path-to-root> gemini
+
+```
+
+### Remote server development (SSH port forwarding)
+
+If you're running Coral on a remote server, forward the dashboard port over SSH to access it in your local browser:
+
+```bash
+# Forward remote port 8420 to localhost:8420
+ssh -L 8420:localhost:8420 user@remote-host
+
+# If using a custom port
+ssh -L 9000:localhost:9000 user@remote-host
+```
+
+Then open `http://localhost:8420` (or your custom port) in your local browser. You can add this to your `~/.ssh/config` to make it persistent:
+
+```
+Host my-dev-server
+    HostName remote-host
+    User user
+    LocalForward 8420 localhost:8420
+```
+
+### Manual tmux management
+
+```bash
+# Attach to a specific agent session
+tmux attach -t claude-agent-1
+
+# Switch between windows
+Ctrl+b n  # next
+Ctrl+b p  # previous
+
+# Detach from tmux
+Ctrl+b d
+```
+
+## Agent Protocol
+
+Agents emit structured markers using the `||PULSE:<EVENT_TYPE> <payload>||` format. The dashboard parses these from agent output in real time:
+
+```
+||PULSE:STATUS <Short description of current task>||
+||PULSE:SUMMARY <One-sentence high-level goal>||
+||PULSE:CONFIDENCE <1-5> <short reason>||
+```
+
+The protocol is automatically injected via `PROTOCOL.md` when launching agents. See [`src/coral/PROTOCOL.md`](src/coral/PROTOCOL.md) for the full specification.
+
+
+## Advanced Information
+
+For information on project structure, API endpoints, and the database schema, please see [DEVELOP.md](DEVELOP.md).
+
+## Dependencies
+
+- Python 3.8+
+- [FastAPI](https://fastapi.tiangolo.com/) + [Uvicorn](https://www.uvicorn.org/) — Web server
+- [Jinja2](https://jinja.palletsprojects.com/) — HTML templating
+- [aiosqlite](https://github.com/omnilib/aiosqlite) — Async SQLite (WAL mode)
+- tmux — Session management
+- Claude CLI (optional) — Powers auto-summarization
+
+## Contributing
+
+We welcome contributions! Whether it's adding support for new AI coding agents natively or improving the web dashboard, please feel free to open an issue or submit a pull request.
+
+## License
+
+This project is licensed under the MIT License.

agent_coral-2.0.0/README.md

@@ -0,0 +1,261 @@
+<img width="1024" height="250" alt="image" src="https://github.com/user-attachments/assets/8b7b1467-ecba-4b63-9151-137f2d2243ec" />
+
+---
+
+## The Pitch
+
+Coral brings sanity to coding with AI agents without disrupting your workflow. The goal is to augment, not take over. Activity across all your agents is visible so you can see which ones need attention at a glance.
+
+Stop losing track of what your AI coding agents are doing. As you scale your workflow, the chaos of scattered terminals, lost context, and untracked changes slows you down. Coral is the mission control center you need to effortlessly orchestrate your entire AI workforce. Maintain total visibility over every agent's progress, organize your history, and automate routine tasks so you can focus on building. Stop fighting your tools and start multiplying your productivity—with all your data completely secure and private on your own machine.
+
+Coral is an MIT-licensed multi-agent orchestration application built with tmux, FastAPI, and vanilla HTML5/JS for easy extensibility and modification. We welcome feedback and contributions.
+
+**[Read the full documentation →](https://cdknorow.github.io/coral/)**
+
+
+![main_loop](https://github.com/user-attachments/assets/6af60c92-1d72-45bd-9b46-7f1eab2ce5fe)
+
+## Features
+
+- **Multi-agent support** — Launch and manage both Claude and Gemini agents side-by-side across worktrees
+- **Web dashboard** — Real-time monitoring with pane capture, status tracking, and command input
+- **Session history** — Browse past sessions with advanced filters (date range, agent type, tags, full-text search)
+- **Full-text search** — Search across all session content using SQLite FTS5 with porter stemming
+- **Auto-summarization** — Sessions are automatically summarized and indexed for search
+- **Scheduled jobs** — Create cron-scheduled tasks that launch agents in isolated worktrees, send prompts, and clean up automatically
+- **Webhook notifications** — Get notified via webhook when agents need input or complete work
+- **Session notes & activity** — Add markdown notes and track activity that occurred in each session, live and historically
+- **Remote control** — Send commands, navigate modes, and manage agents from the dashboard
+- **Attach/Kill/Restart/Resume** — Open a terminal attached to any agent's tmux session, kill it, or relaunch as a new session
+- **Git integration & PR linking** — Tracks commits, branches, and remote URLs per agent and session
+- **Custom macros** — Add configurable toolbar buttons for frequently used commands
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install agent-coral
+```
+
+Or install directly from GitHub:
+
+```bash
+pip install git+https://github.com/cdknorow/coral.git
+```
+
+## Launch agents and web dashboard
+
+You can launch the web server directly using `coral` or `coral-dashboard`:
+
+```bash
+# Start the web dashboard directly (default: http://localhost:8420)
+coral
+
+# Custom host/port
+coral --host 127.0.0.1 --port 9000
+
+```
+
+> **Note:** This system is currently mostly tested with Claude Code and to some extent Gemini CLI. However, the underlying architecture is extensible to any cli based agents.
+
+### Session history search and filtering
+
+![history](https://github.com/user-attachments/assets/3848aefe-e358-425b-ae14-ed2f41704a33)
+
+
+The sidebar History section includes a search bar and filters for browsing your entire AI coding session history along with activity, notes, and git commit tracking
+
+On startup, the server launches three background services:
+
+1. **Session indexer** (every 2 min) — Indexes all Claude sessions from `~/.claude/projects/**/*.jsonl` and Gemini sessions from `~/.gemini/tmp/*/chats/session-*.json`, builds a full-text search index (FTS5), and queues new sessions for auto-summarization
+2. **Batch summarizer** — Continuously processes the summarization queue using Claude CLI
+3. **Git poller** (every 2 min) — Polls git branch, commit, and remote URL for each live agent and stores snapshots in SQLite
+
+Features:
+
+- **Search** — Type in the search bar to find sessions by content (uses SQLite FTS5 with porter stemming)
+- **Filter by tag** — Select a tag from the dropdown to narrow results
+- **Filter by source** — Show only Claude or Gemini sessions
+- **Filter by date** — Narrow results to a specific date range
+- **Pagination** — Browse through all sessions with prev/next controls
+- **URL bookmarking** — Session URLs use hash routing (`#session/<id>`) so you can bookmark or share links
+- **Notes & tags** — Add markdown notes and color-coded tags to any session, stored in `~/.coral/sessions.db`
+
+
+### Managing sessions from the dashboard
+
+<img width="1502" height="812" alt="image" src="https://github.com/user-attachments/assets/9a8d1b7b-1bef-414b-9002-c27dd928342b" />
+
+
+The web dashboard provides quick-action buttons for each live session:
+
+| Action | Description |
+|---|---|
+| **Esc / Arrow / Enter** | Send navigation keys to the agent |
+| **Plan Mode** | Toggle Claude Code plan mode |
+| **Accept Edits** | Toggle Claude Code auto-accept mode |
+| **Bash Mode** | Send `!` command to enter bash mode |
+| **Base Mode** | Toggle base mode |
+| **/compact / /clear** | Send compress or clear commands (adapts per agent type) |
+| **Reset** | Compress then clear the session |
+| **Attach** | Open a local terminal window attached to the agent's tmux session |
+| **Restart** | Restart the agent in the same tmux pane |
+| **Kill** | Terminate the tmux session and remove it from the dashboard |
+
+You can also type arbitrary commands in the input bar and send them to the selected agent.
+
+
+
+### Scheduled Jobs
+
+Coral supports cron-scheduled jobs that automatically launch agents in isolated git worktrees. Create and manage them from the Scheduled section in the sidebar.
+
+Each scheduled job:
+- Creates a fresh git worktree from the specified branch
+- Launches an agent (Claude or Gemini) with optional CLI flags
+- Sends the configured prompt to the agent
+- Monitors the session with a configurable timeout
+- Cleans up the worktree on completion (optional)
+- Tags the session as "scheduled" for easy filtering in history
+
+Run history is tracked per job with links to view each session's full history.
+
+### Webhook Notifications
+
+Configure webhooks from the dashboard settings to receive HTTP notifications when agents need input or when other events occur. Useful for integrating with Slack, Discord, or custom monitoring.
+
+### Claude Code Hooks (settings.json)
+
+To fully integrate Claude Code's agentic state and task management into the Coral dashboard, configure the provided `coral-hook` scripts in your Claude Code `settings.json` (usually located at `~/.claude.json` or `~/.claude/settings.json`).
+
+If you are already using other configuration options like a custom `statusLine` or other hooks, simply merge these hook definitions into your existing JSON:
+
+```json
+"hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "TaskCreate|TaskUpdate",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "coral-hook-task-sync"
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "coral-hook-agentic-state"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "coral-hook-agentic-state"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "coral-hook-agentic-state"
+          }
+        ]
+      }
+    ]
+
+```
+
+
+
+Or use launcher which discovers worktree subdirectories, creates a agent for each one, and starts launches the dashboard:
+
+```bash
+# Launch Claude agents and web dashboard for worktrees in the current directory
+launch-coral
+
+# Launch Gemini agents from a specific path
+launch-coral <path-to-root> gemini
+
+```
+
+### Remote server development (SSH port forwarding)
+
+If you're running Coral on a remote server, forward the dashboard port over SSH to access it in your local browser:
+
+```bash
+# Forward remote port 8420 to localhost:8420
+ssh -L 8420:localhost:8420 user@remote-host
+
+# If using a custom port
+ssh -L 9000:localhost:9000 user@remote-host
+```
+
+Then open `http://localhost:8420` (or your custom port) in your local browser. You can add this to your `~/.ssh/config` to make it persistent:
+
+```
+Host my-dev-server
+    HostName remote-host
+    User user
+    LocalForward 8420 localhost:8420
+```
+
+### Manual tmux management
+
+```bash
+# Attach to a specific agent session
+tmux attach -t claude-agent-1
+
+# Switch between windows
+Ctrl+b n  # next
+Ctrl+b p  # previous
+
+# Detach from tmux
+Ctrl+b d
+```
+
+## Agent Protocol
+
+Agents emit structured markers using the `||PULSE:<EVENT_TYPE> <payload>||` format. The dashboard parses these from agent output in real time:
+
+```
+||PULSE:STATUS <Short description of current task>||
+||PULSE:SUMMARY <One-sentence high-level goal>||
+||PULSE:CONFIDENCE <1-5> <short reason>||
+```
+
+The protocol is automatically injected via `PROTOCOL.md` when launching agents. See [`src/coral/PROTOCOL.md`](src/coral/PROTOCOL.md) for the full specification.
+
+
+## Advanced Information
+
+For information on project structure, API endpoints, and the database schema, please see [DEVELOP.md](DEVELOP.md).
+
+## Dependencies
+
+- Python 3.8+
+- [FastAPI](https://fastapi.tiangolo.com/) + [Uvicorn](https://www.uvicorn.org/) — Web server
+- [Jinja2](https://jinja.palletsprojects.com/) — HTML templating
+- [aiosqlite](https://github.com/omnilib/aiosqlite) — Async SQLite (WAL mode)
+- tmux — Session management
+- Claude CLI (optional) — Powers auto-summarization
+
+## Contributing
+
+We welcome contributions! Whether it's adding support for new AI coding agents natively or improving the web dashboard, please feel free to open an issue or submit a pull request.
+
+## License
+
+This project is licensed under the MIT License.

agent_coral-2.0.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-coral"
+version = "2.0.0"
+description = "A multi-agent orchestration system for managing AI coding agents (Claude and Gemini) in parallel git worktrees with a real-time web dashboard."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+dependencies = [
+    "fastapi>=0.104.0",
+    "uvicorn[standard]>=0.24.0",
+    "jinja2>=3.1.0",
+    "aiosqlite>=0.19.0",
+    "httpx>=0.25.0",
+    "python-multipart>=0.0.6",
+]
+authors = [
+    { name = "Chris Knorowski" }
+]
+keywords = [
+    "ai",
+    "agents",
+    "claude",
+    "gemini",
+    "orchestration",
+    "tmux",
+    "multi-agent",
+    "coding-agents",
+    "dashboard",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Build Tools",
+]
+
+[project.urls]
+Homepage = "https://github.com/cdknorow/coral"
+Repository = "https://github.com/cdknorow/coral"
+Issues = "https://github.com/cdknorow/coral/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "flake8>=6.0.0",
+    "black>=23.0.0",
+    "build>=1.0.0",
+    "twine>=5.0.0",
+]
+
+[project.scripts]
+coral = "coral.web_server:main"
+coral-dashboard = "coral.web_server:main"
+launch-coral = "coral.launch:main"
+coral-hook-task-sync = "coral.hooks.task_state:main"
+coral-hook-agentic-state = "coral.hooks.agentic_state:main"
+# Legacy aliases (migration from corral -> coral)
+corral = "coral.web_server:main"
+launch-corral = "coral.launch:main"
+
+[tool.setuptools.package-data]
+coral = ["PROTOCOL.md", "launch_agents.sh", "templates/*.html", "templates/includes/*.html", "templates/includes/views/*.html", "static/*.css", "static/css/*.css", "static/*.js", "static/*.png", "static/*.ico", "bundled_themes/*.json"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

agent_coral-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+