ai-comm

ai-comm

Cross-AI CLI communication tool for Kitty terminal. Enables AI assistants running in separate Kitty windows to communicate with each other.

Why ai-comm?

When working with multiple AI coding assistants, you may want them to collaborate—code review across models, second opinions on architecture, or delegating specialized tasks.

Why terminal text instead of MCP or black magic?

• Stability: AI CLI tools evolve rapidly, with many still at 0.x and frequently introducing breaking changes. Terminal UI, being user-facing, remains far more stable.
• Lightweight: MCP tools consume significant context (often tens of thousands of tokens at startup) and can cause attention dilution. ai-comm uses simple shell commands with minimal overhead.
• No infrastructure: Each AI CLI maintains its own context. No need for external services like Redis to synchronize state across tools.
• Composability: Shell pipelines and REPL patterns combine naturally, leveraging what CLIs already do well.

Setup

1. Install ai-comm

# From PyPI
uv tool install ai-comm

# Or from GitHub
uv tool install git+https://github.com/eigenigma/ai-comm.git

2. Configure Kitty

Enable remote control in ~/.config/kitty/kitty.conf:

allow_remote_control socket-only
listen_on unix:/tmp/kitty-${USER}

3. Configure Your AI

Add instructions to your AI’s project file (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) or skills system. See docs/AGENTS.md for reference configuration. An example Claude Code skill is provided in docs/skills/ai-comm/.

Usage

1. Open multiple AI CLIs in separate Kitty windows:

   claude    # Window 1
   codex     # Window 2
   gemini    # Window 3
   

2. Ask your AI to collaborate:

   “Use ai-comm to ask Codex to review src/main.py”

   The AI discovers available windows and sends the request:

   ai-comm list-ai-windows
   #   ID  CLI         TITLE                           CWD
   #   11  codex       Reviewing authentication        /home/user/project
   #   21  gemini      Analyzing database schema       /home/user/project
   
   ai-comm send "Review src/main.py for bugs" -w 11
   # Returns Codex's response
   

3. For long responses, instruct the target AI to write to a file:

   ai-comm send "Write analysis to report_$(date +%Y%m%d_%H%M%S).md" -w 11
   

Supported CLIs

Troubleshooting

“Window not found”: Ensure the AI CLI is running in Kitty and remote control is enabled. Run ai-comm list-ai-windows to verify.

Empty responses: For long outputs, ask the AI to write to a file instead of returning directly.

“Kitty I/O timeout”: Check if Kitty is responsive; try restarting it.

Development

git clone https://github.com/eigenigma/ai-comm.git
cd ai-comm
uv sync

uv run ai-comm --help
uv run ruff check src/
uv run mypy src/

Adding a New CLI

1. Add entry in src/ai_comm/registry.py
2. Create adapter in src/ai_comm/adapters/<name>.py (class {Name}Adapter)
3. Add detection in src/ai_comm/kitten/ai_comm_kitten.py

License

MIT