{"id":30218267,"url":"https://github.com/Intelligent-Internet/CommonGround","last_synced_at":"2025-08-14T06:05:29.382Z","repository":{"id":305846317,"uuid":"1021235121","full_name":"Intelligent-Internet/CommonGround","owner":"Intelligent-Internet","description":"An open-source application for building, observing, and collaborating with teams of AI agents.","archived":false,"fork":false,"pushed_at":"2025-08-13T03:32:40.000Z","size":5623,"stargazers_count":371,"open_issues_count":2,"forks_count":48,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-08-13T05:34:14.208Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Intelligent-Internet.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}},"created_at":"2025-07-17T05:22:40.000Z","updated_at":"2025-08-13T03:32:43.000Z","dependencies_parsed_at":"2025-07-22T10:40:07.338Z","dependency_job_id":null,"html_url":"https://github.com/Intelligent-Internet/CommonGround","commit_stats":null,"previous_names":["intelligent-internet/commonground"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Intelligent-Internet/CommonGround","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intelligent-Internet%2FCommonGround","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intelligent-Internet%2FCommonGround/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intelligent-Internet%2FCommonGround/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intelligent-Internet%2FCommonGround/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Intelligent-Internet","download_url":"https://codeload.github.com/Intelligent-Internet/CommonGround/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intelligent-Internet%2FCommonGround/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270372302,"owners_count":24572346,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-14T02:00:10.309Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-08-14T06:03:02.417Z","updated_at":"2025-08-14T06:05:29.352Z","avatar_url":"https://github.com/Intelligent-Internet.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Common Ground\n\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Twitter Follow](https://img.shields.io/twitter/follow/ii_posts?style=social)](https://twitter.com/ii_posts)\n\n![Common Ground Title Image](assets/title.png)\n\nAn open-source application for building, observing, and collaborating with teams of AI agents.\n\nCommon Ground allows you to construct sophisticated multi-agent systems that can tackle complex research and analysis tasks. It combines a powerful **Partner-Principal-Associate** agent architecture with a rich, real-time web interface, turning complex AI processes into transparent, manageable, and collaborative workflows.\n\n![Common Ground Demo GIF](assets/demo.gif)\n\n## ✨ Key Features\n\n*   **🧠 Advanced Multi-Agent Architecture**: Simulate a real-world consulting team with a `Partner` agent for user interaction, a `Principal` for planning and task decomposition, and specialized `Associate` agents for execution.\n\n*   **📄 Declarative Agent Design**: No-code/low-code agent customization. Define complex agent behaviors, prompts, tool access, and even context-passing protocols in simple, human-readable **YAML files**.\n\n*   **🔭 Full Observability Suite**: Go beyond `print()` debugging. Visualize your agent team's execution in real-time with dynamic **Flow**, **Kanban**, and **Timeline** views. Understand every decision, tool call, and state change.\n\n*   **🛠️ Extensible \u0026 Unified Tooling**: Easily integrate custom Python tools or external APIs via the Model Context Protocol (MCP). All capabilities are treated as standardized tools that any agent can use.\n\n*   **🔌 Model Agnostic with Gemini Out-of-the-Box**: Powered by `LiteLLM`, the framework supports any major LLM provider. The default Docker setup includes a pre-configured bridge for seamless Google Gemini integration.\n\n*   **🗂️ Built-in Project \u0026 Knowledge Management**: Organize your runs into projects, manage files, and leverage an auto-updating RAG system that indexes your workspace to provide agents with relevant, up-to-date context.\n\n## 🤔 Why Common Ground?\n\nIn a world of increasingly complex AI agents, `Common Ground` focuses on the critical missing piece: **truly effective human-AI collaboration**.\n\n\u003e Our philosophy is to create a **\"common ground\"** where human intuition and AI's computational power can meet. We do this by providing deep observability into not just *what* the agents are doing, but *why*, transforming the user from a passive prompter into an active \"pilot in the cockpit.\"\n\nThis framework is for you if you want to:\n*   Build agents that can handle multi-step, research-heavy tasks.\n*   Move beyond simple command-response chains to strategic, collaborative workflows.\n*   Easily customize and experiment with different agent behaviors without rewriting core logic.\n*   Have a system that is transparent and debuggable by design.\n\n## 🚀 Getting Started\n\n### Mode 1: Recommended Deployment (Docker)\n\nThis is the easiest way to get the full system running, including the pre-configured `gemini-cli-bridge` for multi-agent mode.\n\n**Prerequisites**:\n*   Docker \u0026 Docker Compose\n*   Git\n\n**Steps**:\n\n1.  **Clone the Repository**:\n    ```bash\n    git clone https://github.com/Intelligent-Internet/CommonGround\n    cd CommonGround\n    ```\n\n2.  **Initialize Git Submodules**:\n    This step is crucial to pull in the `gemini-cli-mcp-openai-bridge`.\n    ```bash\n    git submodule update --init --recursive\n    ```\n\n3.  **Navigate to Deployment Directory**:\n    All `docker compose` commands must be run from this directory.\n    ```bash\n    cd deployment\n    ```\n\n4.  **Authenticate with Google (First-Time Setup via Gemini-CLI OAuth)**:\n    You can skip this step if you have already authenticated with Gemini CLI on your host machine.\n    If you haven't run Gemini-CLI on your host machine before, run this command to start an interactive login.\n    ```bash\n    docker compose run --rm --service-ports login\n    ```\n    Follow the on-screen instructions, set the theme, select authentication method, and click the authorization link. Your credentials will be saved in `~/.gemini/` on your host machine for future use. You can then exit the CLI with `ctrl+c` or `/quit`.\n    * `Login with Google` is recommended - It runs Gemini-CLI via Code Assist Subscription, which is free for personal use as of today (July 2025), see [Gemini CLI](https://github.com/google-gemini/gemini-cli) for more details.\n    \u003e **📌 Troubleshooting: `GOOGLE_CLOUD_PROJECT` Error**\n    \u003e\n    \u003e If you encounter an error like `Failed to login. Message: This account requires setting the GOOGLE_CLOUD_PROJECT env var`, you must explicitly provide your Google Cloud Project ID.\n    \u003e\n    \u003e 1.  Find your Project ID in the [Google Cloud Console](https://console.cloud.google.com/).\n    \u003e 2.  Open the `deployment/docker-compose.yaml` file.\n    \u003e 3.  In the `bridge` service section, find and uncomment the `GOOGLE_CLOUD_PROJECT` environment variable, replacing `your_google_cloud_project_id_here` with your actual ID:\n    \u003e     ```yaml\n    \u003e     services:\n    \u003e       bridge:\n    \u003e         # ... other settings\n    \u003e         environment:\n    \u003e           # ...\n    \u003e           - GOOGLE_CLOUD_PROJECT=your_google_cloud_project_id_here\n    \u003e     ```\n    \u003e 4.  Save the file and re-run the `docker compose run ... login` command.\n    \u003e\n    \u003e For more details, see the related [gemini-cli issue](https://github.com/google-gemini/gemini-cli/issues/2262#issuecomment-3045275406).\n    * If you prefer to use other authentication methods other than automatic OAuth, installing and configuring the `gemini-cli` tool on your host machine is recommended. You can then point the `gemini-cli-bridge` to your local `.gemini` directory, and comment out the `login` service in the `docker-compose.yaml` file.\n      * Don't forget to set environment variables in the `bridge` service section of `docker-compose.yaml` if you want to use API key authentication instead of OAuth.\n    * You can safely quit the Gemini CLI after logging in, as the credentials are saved in the `.gemini` directory.\n\n    **Alternative: Using API Key Authentication**\n    \n    If you prefer to use a Gemini API key instead of OAuth authentication, you can skip the login step entirely:\n    \n    1. Create a `.env` file in the `deployment` directory with your Gemini API key:\n       ```bash\n       # In the deployment directory, create a .env file\n       echo \"GEMINI_API_KEY=your_gemini_api_key_here\" \u003e .env\n       ```\n       Or create it manually with the following content:\n       ```\n       GEMINI_API_KEY=your_gemini_api_key_here\n       ```\n    \n    2. Use the API key configuration file to start the services:\n       ```bash\n       docker compose -f ./docker-compose.api-key.yaml up\n       ```\n    \n    This approach bypasses the OAuth flow and directly uses your API key for authentication with Google's Gemini service.\n\n5.  **Start All Services**:\n    This command builds the images (if they don't exist) and starts all services.\n    ```bash\n    docker compose up \n    ```\n    If you want to rebuild the images from source, use:\n    ```bash\n    docker compose up --build\n    ```\n    To run in the background, add the `-d` flag: `docker compose up --build -d`.\n\n6.  **Access the Application**:\n    Open your browser and navigate to: **[http://localhost:8000](http://localhost:8000)**\n\n### Mode 2: For Developers (Local Setup)\n\nThis mode is for developers who want to modify the core application or use different LLM providers.\n\n**Prerequisites**:\n*   Python 3.12+\n*   Node.js \u0026 npm/yarn\n*   `uv` (run `pip install uv` for fast Python package management)\n\n**Steps**:\n\n\n#### Step 1: Start gemini-cli-mcp-openai-bridge\n\n```bash\ngit submodule update --init --recursive\ncd deployment/gemini-cli-mcp-openai-bridge\n# Follow the README instructions to start gemini-cli-mcp-openai-bridge and make sure it is running successfully\n```\nWe will use this bridge to enable Gemini support for Common Ground.\n\n#### Step 2: Start the Backend Service\n\n```bash\ncd core\nuv venv           # Create a virtual environment\nuv sync           # Install Python dependencies\ncp env.sample .env # Create your local environment file\n# Edit .env to configure your LLM provider if not using the default\nuv run run_server.py\n```\nOnce started, the backend will be available at: `http://localhost:8000`.\n\n#### Step 3: Start the Frontend Service\n\nOpen a **new terminal** and run:\n```bash\ncd frontend\ncp .env.example .env.local\nnpm install\nnpm run dev\n```\nOnce started, the frontend will be available at: `http://localhost:3000`.\n\n## 🛠️ Customization \u0026 Extensibility\n\nThe framework is designed to be easily extended without modifying the core engine. Here are the primary customization points:\n\n*   **Define Agent Behavior**:\n    Modify or create new YAML files in `core/agent_profiles/profiles/`. This is where you define an agent's role, thinking process (`flow_decider`), and tool access (`tool_access_policy`).\n\n*   **Add a New Tool**:\n    Create a new Python file in `core/agent_core/nodes/custom_nodes/`. Define a class inheriting from `BaseToolNode` and decorate it with `@tool_registry`. The framework will automatically discover and integrate it.\n\n*   **Configure LLMs**:\n    Add or edit YAML files in `core/agent_profiles/llm_configs/`. You can define new LLM providers, set different models for different agents, and manage API keys securely using environment variables.\n\n*   **Create Handover Protocols**:\n    For complex agent interactions (like a Principal assigning a task to an Associate), define a data-passing contract in `core/agent_profiles/handover_protocols/`.\n\n\u003e For detailed instructions, please see the [**Guides**](./docs/guides/) directory.\n\n## 🏛️ Architecture Overview\n\nThe system uses a well-defined collaborative flow to tackle complex tasks, with its core interactions illustrated below:\n\n```mermaid\ngraph TD\n    User[\"User (via Web UI)\"] -- \"1: Input research question\" --\u003e PartnerAgent[\"Partner Agent (Strategic Partner)\"]\n    PartnerAgent -- \"2: Dialogue, plan, and create Work Modules\" --\u003e PrincipalAgent[\"Principal Agent (Project Lead)\"]\n    PrincipalAgent -- \"3: Dispatches modules to\" --\u003e AssociateAgents[\"Parallel Associate Agents (Executors)\"]\n    AssociateAgents -- \"4: Execute specific tasks (e.g., search, analyze)\" --\u003e AssociateAgents\n    AssociateAgents -- \"5: Return deliverables\" --\u003e PrincipalAgent\n    PrincipalAgent -- \"6. Review, integrate, and generate final report\" --\u003e FinalReport[\"Final Report\"]\n\n    subgraph \"Real-time Communication (WebSocket)\"\n        PartnerAgent -- \"Status \u0026 thoughts\" --\u003e WSServer[\"Server\"]\n        PrincipalAgent -- \"Status \u0026 thoughts\" --\u003e WSServer\n        AssociateAgents -- \"Status \u0026 thoughts\" --\u003e WSServer\n        WSServer -- \"Streaming Updates\" --\u003e User\n    end\n```\nFor a deeper dive into the architecture, please see our [architecture documentation](./docs/architecture.md), and framework documents in the `docs/` directory.\n\n## 📈 Changelog\n\n### Recent Updates (July 2025)\n\n#### v0.1.2 - Core Logic Refinements and Developer Experience\n*Released: July 25, 2025*\n\n[Important BUG FIX] This release includes a critical fix to address context leaking, significantly reducing token usage and improving overall system performance.\n\n**🧠 Core Agent \u0026 LLM Enhancements**\n- **Internal Message Handling**: Added an `_internal._no_handover` flag to prevent handover of inherited messages between agents.\n- **Smarter Pre-execution Checks**: Added a pre-launch check to ensure an actionable plan exists before tool execution.\n\n**🎨 Frontend \u0026 UX**\n- **Real-time Project Sync**: Project updates are now broadcast to all active user sessions, ensuring state consistency.\n\n**🔧 Developer Experience \u0026 Miscellaneous**\n- **VS Code Integration**: Added Visual Studio Code launch and task configurations for easier backend and frontend development.\n  - Note: you might need to adjust these files to match your local environment.\n- **Configuration Updates**: Updated the model name for `gemini-flash-lite`, removed unused configuration files, and corrected LLM configuration references in agent profiles.\n- **Documentation Fixes**: Removed an outdated Discord link from the documentation.\n\n#### v0.1.1 - Tool Calling Improvements and UI Enhancements\n*Released: July 22, 2025*\n\n**🛠️ Tool System Enhancements**\n- **Refactored Ingestor System**: Implemented a new recursive Markdown formatter for better content presentation to LLMs\n- **Robust Tool Calling**: Significantly improved tool execution reliability and error handling\n- **Updated Tool Naming**: Changed tool name separator from dot to underscore for consistency \u003c- This fixes issues with Gemini-CLI tool calls\n- **Better Error Recovery**: Enhanced retry mechanisms and failure handling for tool operations\n- **Improved Agent Prompts**: Refined system prompts for better agent performance and clearer instructions\n\n**🎨 Frontend Enhancements**\n- **New Thinking Indicator**: Added visual \"thinking\" dots to chat bubbles when agents are processing, providing real-time feedback on system activity\n- **Improved User Feedback**: Better visual cues for running agent turns to enhance user experience\n\n**🔧 Miscellaneous**\n- **Documentation Updates**: Improved clarity and detail in Gemini-CLI API key setup instructions\n\n#### v0.1.0 - Initial Release\n\n## 🧑‍💻 Contributing\n\nWe welcome contributions! Please read our [**Contribution Guide**](./CONTRIBUTING.md) and check out the detailed guides in the `docs/` directory to get started.\n\n## 💬 Community \u0026 Support\n\n*   **Discord**: Join our community on [Discord](https://discord.gg/VBD2yybb) for help, discussion, and collaboration.\n*   **GitHub Issues**: Found a bug or have a feature request? [Open an issue](https://github.com/Intelligent-Internet/CommonGround/issues).\n\n## 📄 License\n\nThis project is licensed under the Apache-2.0 License. See the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIntelligent-Internet%2FCommonGround","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FIntelligent-Internet%2FCommonGround","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIntelligent-Internet%2FCommonGround/lists"}