otto-agent 0.1.0__tar.gz

otto_agent-0.1.0/.claude/plans/session-new-fork.md

@@ -0,0 +1,375 @@
+# Session Creation & Forking via Tool Call
+
+## Overview
+
+Add a `session_new` MCP tool that lets the LLM create new sessions (fresh or forked) mid-conversation. Also add a `fork_session` function to `sessions.py` that copies the current session's conversation history into a new session.
+
+---
+
+## File Changes
+
+### 1. `otto/sessions.py` — Add `fork_session()`
+
+**Insert after `new_session()` (after line 192).**
+
+```python
+def fork_session(
+    topic: str | None = None,
+    chat_id: str | None = None,
+) -> dict:
+    """
+    Fork the current session: archive it and create a new session
+    pre-loaded with the current conversation history.
+
+    Args:
+        topic: Optional topic for the forked session
+        chat_id: Chat ID to scope to
+
+    Returns:
+        The new (forked) session dict with copied messages
+    """
+    _ensure_dirs()
+
+    target = _chat_file(chat_id)
+    lock = _lock_for(target)
+
+    with lock:
+        # Read current session
+        current = None
+        if target.exists():
+            try:
+                current = json.loads(target.read_text())
+            except json.JSONDecodeError:
+                pass
+
+        if current is None or not current.get("messages"):
+            # Nothing to fork — just create a fresh session
+            # Release lock, call new_session (which acquires its own lock)
+            pass
+        else:
+            # Archive the current session
+            if current.get("messages"):
+                archive_session(current)
+
+            # Create new session with copied messages
+            fork_topic = topic or current.get("topic")
+            session_id = _generate_session_id(fork_topic)
+            session = {
+                "id": session_id,
+                "created": datetime.now().isoformat(),
+                "topic": fork_topic,
+                "messages": list(current["messages"]),  # shallow copy
+                "metadata": {
+                    "last_backend": current.get("metadata", {}).get("last_backend"),
+                    "message_count": current.get("metadata", {}).get("message_count", 0),
+                    "chat_id": chat_id,
+                    "forked_from": current.get("id"),
+                },
+            }
+
+            target.write_text(json.dumps(session, indent=2))
+            return session
+
+    # Fallback: nothing to fork
+    return new_session(topic=topic, archive_current=True, chat_id=chat_id)
+```
+
+**Key details:**
+- `fork_session` reads the current session under lock, archives it, then writes a new session that carries over `messages` (shallow copy is fine — messages are plain dicts).
+- Adds `metadata.forked_from` so we know it was forked.
+- If there's no current session or it has no messages, falls back to `new_session()`.
+- The `topic` parameter is optional; if omitted, inherits the current session's topic.
+
+---
+
+### 2. `otto/mcp_tools/session.py` — Add `session_new()` tool
+
+**Append after `session_switch()` (after line 221).**
+
+```python
+async def session_new(
+    mode: str = "fresh",
+    topic: str | None = None,
+    starter_prompt: str | None = None,
+    chat_id: str | None = None,
+) -> dict[str, Any]:
+    """Create a new session, either fresh or forked from the current one.
+
+    Use this when the user wants to start a new conversation topic, or when
+    they want to branch off the current conversation into a new session.
+
+    Args:
+        mode: "fresh" for a blank session, "fork" to copy current history,
+              "ask" to prompt the user to choose (sends Telegram buttons)
+        topic: Optional topic/name for the new session
+        starter_prompt: Initial message to seed the session with (fresh mode only).
+                        Added as the first user message so the LLM has context.
+        chat_id: Chat ID to scope to (auto-detected if omitted)
+    """
+    try:
+        resolved_chat_id = _resolve_chat_id(chat_id)
+
+        if mode == "ask":
+            # Send inline buttons asking fork vs fresh
+            from otto.mcp_tools.platform import send_buttons as _send_buttons
+
+            buttons = [
+                {"label": "Fork (keep context)", "callback_data": "sess_new:fork"},
+                {"label": "Fresh (blank)", "callback_data": "sess_new:fresh"},
+            ]
+            # Include topic in callback data if provided (fits in 64 bytes)
+            if topic:
+                # Truncate topic to fit: "sess_new:fork:<topic>" <= 64 bytes
+                max_topic = 64 - len("sess_new:fork:") - 1
+                short_topic = topic[:max_topic]
+                buttons = [
+                    {"label": "Fork (keep context)", "callback_data": f"sess_new:fork:{short_topic}"},
+                    {"label": "Fresh (blank)", "callback_data": f"sess_new:fresh:{short_topic}"},
+                ]
+
+            result = await _send_buttons(
+                text=f"<b>New session</b>{f': {topic}' if topic else ''}\n\nKeep current conversation context or start blank?",
+                buttons=buttons,
+                chat_id=resolved_chat_id,
+            )
+
+            if not result.get("success"):
+                return _error(result.get("error", "Failed to send buttons"))
+
+            return _ok({
+                "awaiting_choice": True,
+                "message": "Asked the user to choose between fork and fresh. Wait for their button press.",
+            })
+
+        # Auto-title outgoing session before archiving
+        try:
+            await sessions.maybe_auto_title(chat_id=resolved_chat_id, force=True)
+        except Exception:
+            pass
+
+        if mode == "fork":
+            session = await asyncio.to_thread(
+                sessions.fork_session, topic=topic, chat_id=resolved_chat_id
+            )
+            forked_from = session.get("metadata", {}).get("forked_from")
+            return _ok({
+                "created": True,
+                "mode": "fork",
+                "session": {
+                    "id": session.get("id"),
+                    "topic": session.get("topic") or "(untitled)",
+                    "message_count": session.get("metadata", {}).get(
+                        "message_count", len(session.get("messages", []))
+                    ),
+                    "forked_from": forked_from,
+                },
+            })
+
+        # Default: fresh session
+        session = await asyncio.to_thread(
+            sessions.new_session, topic=topic, archive_current=True, chat_id=resolved_chat_id
+        )
+
+        # Seed with starter prompt if provided
+        if starter_prompt and starter_prompt.strip():
+            await asyncio.to_thread(
+                sessions.add_message,
+                role="user",
+                content=starter_prompt.strip(),
+                chat_id=resolved_chat_id,
+            )
+
+        return _ok({
+            "created": True,
+            "mode": "fresh",
+            "session": {
+                "id": session.get("id"),
+                "topic": session.get("topic") or "(untitled)",
+                "message_count": 1 if starter_prompt else 0,
+            },
+            "starter_prompt": starter_prompt if starter_prompt else None,
+        })
+
+    except Exception as exc:
+        return _error(str(exc))
+```
+
+**Key details:**
+- `mode="fresh"` (default): calls `sessions.new_session()`, optionally seeds with `starter_prompt` via `add_message(role="user")`.
+- `mode="fork"`: calls `sessions.fork_session()`, copies full conversation history.
+- `mode="ask"`: uses the existing `send_buttons` platform tool to present inline keyboard buttons. The callback data format is `sess_new:{mode}` or `sess_new:{mode}:{topic}`, always within the 64-byte limit.
+- `starter_prompt` is only used in fresh mode — it's the "let's start a new session about caramel popcorn" seed text.
+- Auto-titles the outgoing session before archiving (same pattern as `cmd_new` at `commands.py:511-514`).
+
+---
+
+### 3. `otto/mcp_tools/__init__.py` — Register `session_new`
+
+**Line 29** — add to import:
+
+```python
+from .session import session_list, session_new, session_switch
+```
+
+**Line 58-59** — add to `ALL_TOOLS` tuple (after `session_switch`):
+
+```python
+    session_switch,
+    session_new,
+)
+```
+
+**Line 95** — add to `__all__` list (after `"session_switch"`):
+
+```python
+    "session_new",
+```
+
+---
+
+### 4. `otto/chat/telegram/callbacks.py` — Add `sess_new` special handler
+
+The `sess_new` callback handles the fork/fresh button press from `mode="ask"`. This needs to be a special handler because it performs session operations and sends a confirmation message.
+
+**Add handler method before `_special_handlers` dict (before line 396):**
+
+```python
+    async def _handle_sess_new(
+        self, query, context: ContextTypes.DEFAULT_TYPE, value: str
+    ) -> CommandResult:
+        """Handle session new/fork choice from inline buttons."""
+        from otto.sessions import fork_session, maybe_auto_title, new_session
+
+        chat_id = str(query.message.chat_id) if query.message else None
+
+        # Parse value: "fork" or "fresh" or "fork:<topic>" or "fresh:<topic>"
+        parts = value.split(":", 1)
+        mode = parts[0]  # "fork" or "fresh"
+        topic = parts[1] if len(parts) > 1 else None
+
+        if mode == "cancel":
+            return CommandResult.ok("Session creation cancelled.")
+
+        # Auto-title outgoing session
+        try:
+            await maybe_auto_title(chat_id=chat_id, force=True)
+        except Exception:
+            pass
+
+        if mode == "fork":
+            session = fork_session(topic=topic, chat_id=chat_id)
+            forked_from = session.get("metadata", {}).get("forked_from", "")
+            topic_display = session.get("topic") or "(untitled)"
+            msg_count = session.get("metadata", {}).get(
+                "message_count", len(session.get("messages", []))
+            )
+            return CommandResult.ok(
+                f"<b>Session forked</b>\n\n"
+                f"Topic: {topic_display}\n"
+                f"Messages carried over: {msg_count}\n"
+                f"Forked from: <code>{forked_from[:20]}</code>"
+            )
+
+        # Fresh session
+        session = new_session(topic=topic, archive_current=True, chat_id=chat_id)
+        topic_display = session.get("topic") or "(no topic)"
+        return CommandResult.ok(f"<b>Fresh session started</b>\n\nTopic: {topic_display}")
+```
+
+**Line 396-400** — add `"sess_new"` to `_special_handlers`:
+
+```python
+    _special_handlers = {
+        "vtt": _handle_vtt_enable,
+        "task_add": _handle_task_add,
+        "gw_permit": _handle_gateway_permit,
+        "sess_new": _handle_sess_new,
+    }
+```
+
+---
+
+## Callback Data Format
+
+All callback data strings must fit in **64 bytes** (Telegram limit).
+
+| Callback data | Bytes | Description |
+|---|---|---|
+| `sess_new:fork` | 14 | Fork without topic |
+| `sess_new:fresh` | 15 | Fresh without topic |
+| `sess_new:fork:<topic>` | 14 + topic | Fork with topic (topic truncated to fit) |
+| `sess_new:fresh:<topic>` | 15 + topic | Fresh with topic (topic truncated to fit) |
+| `sess_new:cancel` | 15 | Cancel |
+
+Max topic length in callback: `64 - 15 = 49 bytes` (for fresh mode, the longer prefix). Safe truncation at 45 chars.
+
+---
+
+## User Scenarios & Tool Call Flow
+
+### Scenario 1: "Start a new session" (no context)
+
+LLM calls:
+```json
+{"tool": "session_new", "args": {"mode": "fresh"}}
+```
+
+Result: Archives current session, creates blank session. LLM tells user "Started a fresh session."
+
+### Scenario 2: "Let's start a new session about caramel popcorn"
+
+LLM calls:
+```json
+{"tool": "session_new", "args": {"mode": "fresh", "topic": "caramel popcorn", "starter_prompt": "Let's discuss caramel popcorn recipes and techniques."}}
+```
+
+Result: Archives current, creates new session with topic "caramel popcorn", adds starter prompt as first user message. LLM's next response will be in the context of the new session.
+
+### Scenario 3: "Fork this session to discuss feature X"
+
+LLM calls:
+```json
+{"tool": "session_new", "args": {"mode": "fork", "topic": "feature X discussion"}}
+```
+
+Result: Archives current session, creates new session with full conversation history copied over, topic set to "feature X discussion". `metadata.forked_from` records the original session ID.
+
+### Scenario 4: "Create a new session" (ambiguous)
+
+LLM calls:
+```json
+{"tool": "session_new", "args": {"mode": "ask"}}
+```
+
+Result: Sends Telegram inline buttons: [Fork (keep context)] [Fresh (blank)]. Tool returns `awaiting_choice: true`. User taps a button, `sess_new` callback handler processes it.
+
+---
+
+## Edge Cases
+
+1. **No current session / empty session for fork**: `fork_session` falls back to `new_session()` if there's nothing to copy. The tool result still shows `mode: "fork"` but `message_count: 0`.
+
+2. **`starter_prompt` with fork mode**: Ignored. Fork copies history as-is. The tool docstring makes this clear: "fresh mode only".
+
+3. **Very long topic in callback data**: Truncated to fit 64-byte Telegram limit. The `session_new` tool truncates `topic` before embedding in callback data.
+
+4. **Concurrent session creation**: File locking via `_lock_for()` (already used by `new_session` and `fork_session`) prevents race conditions.
+
+5. **Auto-titling outgoing session**: Both fresh and fork modes call `maybe_auto_title(force=True)` before archiving, matching the existing pattern in `cmd_new` (line 511-514) and `cmd_switch` (line 1059-1062).
+
+6. **`mode="ask"` with no Telegram platform**: `send_buttons` will fail gracefully with an error message. The LLM can fall back to asking in text.
+
+---
+
+## Summary of Changes
+
+| File | Change | Lines |
+|---|---|---|
+| `otto/sessions.py` | Add `fork_session()` | Insert after line 192 |
+| `otto/mcp_tools/session.py` | Add `session_new()` tool | Append after line 221 |
+| `otto/mcp_tools/__init__.py` | Import + register `session_new` | Lines 29, 58, 95 |
+| `otto/chat/telegram/callbacks.py` | Add `_handle_sess_new` + register in `_special_handlers` | Before line 396 |
+
+No changes needed to `renderer.py` — the existing `_handle_result` flow handles `CommandResult.ok()` from the new callback handler.
+
+No changes needed to `commands.py` — the `/new` command continues to work as before. The MCP tool is an independent path.

otto_agent-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python build artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Virtual environments
+.venv/
+
+# Local runtime state (should live under ~/.otto/, not the repo)
+.otto/
+.ada/
+.brainfile/
+logs/
+photos/
+sessions/
+
+# Local data files
+data/*.db
+data/*.sqlite
+data/*.sqlite*
+jobs.db
+
+# Secrets and mutable config (keep config/.env.example tracked)
+config/.env
+config/bot_state.json
+config/conversation.json
+config/conversation.json.bak
+
+# Logs
+*.log
+
+# OS/editor
+.DS_Store
+
+# Generated files and local configs
+report.md
+otto-mcp-catalog.yaml
+.mcp.json
+.gemini/

otto_agent-0.1.0/Makefile

@@ -0,0 +1,49 @@
+.PHONY: help install reload stop start status test lint format check logs clean
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install otto as editable uv tool
+	yes | uv tool install --force --editable .
+
+reload: stop install start status ## Stop, reinstall, restart, verify
+
+stop: ## Stop all services and kill stragglers
+	@otto service stop all 2>/dev/null || true
+	@pkill -f "otto.services.telegram" 2>/dev/null || true
+	@pkill -f "otto.services.worker" 2>/dev/null || true
+	@pkill -f "codex app-server" 2>/dev/null || true
+	@sleep 1
+	@TCOUNT=$$(pgrep -fc "otto.services.telegram" 2>/dev/null || echo 0); \
+	 WCOUNT=$$(pgrep -fc "otto.services.worker" 2>/dev/null || echo 0); \
+	 if [ "$$TCOUNT" -gt 0 ] || [ "$$WCOUNT" -gt 0 ]; then \
+	   pkill -9 -f "otto.services.telegram" 2>/dev/null || true; \
+	   pkill -9 -f "otto.services.worker" 2>/dev/null || true; \
+	   sleep 1; \
+	 fi
+
+start: ## Start all services
+	otto service start all
+
+status: ## Show service status
+	@otto service status
+	@echo ""
+	@ps aux | grep -E "otto.services" | grep -v grep || echo "No otto processes found"
+
+test: ## Run test suite
+	python -m pytest tests/ -x -q
+
+lint: ## Lint with ruff
+	ruff check otto/ tests/
+
+format: ## Format with ruff
+	ruff format otto/ tests/
+
+check: lint test ## Lint + test
+
+logs: ## Tail telegram log
+	tail -f ~/.otto/logs/telegram.log
+
+clean: ## Remove build artifacts and caches
+	rm -rf build/ dist/ *.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

otto_agent-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: otto-agent
+Version: 0.1.0
+Summary: Otto - MCP gateway, agent orchestration, and automation framework
+Project-URL: Homepage, https://github.com/1broseidon/otto
+Project-URL: Documentation, https://otto-agent.dev
+Project-URL: Repository, https://github.com/1broseidon/otto
+Project-URL: Issues, https://github.com/1broseidon/otto/issues
+Author-email: George <george@example.com>
+License-Expression: MIT
+Keywords: agent,automation,cli,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: claude-agent-sdk>=0.1.29
+Requires-Dist: croniter>=2.0.0
+Requires-Dist: litellm>=1.81.8
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: python-telegram-bot[job-queue]>=20.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: generic
+Requires-Dist: litellm>=1.0.0; extra == 'generic'
+Provides-Extra: sdk
+Requires-Dist: claude-agent-sdk>=0.1.29; extra == 'sdk'
+Provides-Extra: vtt
+Requires-Dist: faster-whisper; extra == 'vtt'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/otto-logo.png" alt="Otto" width="200" />
+</p>
+
+<h1 align="center">Otto</h1>
+
+<p align="center">
+  <strong>Your personal AI agent that actually gets things done.</strong>
+</p>
+
+<p align="center">
+  <a href="#"><img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build Status" /></a>
+  <a href="#"><img src="https://img.shields.io/badge/version-0.1.0-blue" alt="Version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License" /></a>
+  <a href="#"><img src="https://img.shields.io/badge/python-3.10+-yellow" alt="Python" /></a>
+</p>
+
+<p align="center">
+  <a href="#quick-install">Install</a> •
+  <a href="#features">Features</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="docs/guide/01-architecture.md">Docs</a> •
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+Otto is a self-hosted AI assistant that lives on your infrastructure and talks to you through Telegram. She can spawn background agents, run scheduled tasks, manage your tools through an MCP gateway, and actually remember what you talked about last week.
+
+No cloud platform. No vendor lock-in. Just your own AI agent that works for you.
+
+## Quick Install
+
+**One-liner:**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/1broseidon/otto/main/install.sh | bash
+```
+
+**Or clone and install:**
+
+```bash
+git clone https://github.com/1broseidon/otto.git ~/agent
+cd ~/agent && ./install.sh
+```
+
+The installer sets up everything: Python environment, dependencies, and prompts for your Telegram bot token.
+
+## Features
+
+### 🌐 MCP Gateway with Tool Routing
+Unified tool access through the Model Context Protocol. Connect filesystem, browser, search, and custom tools—configured once, available to all backends. Policy-based access control keeps things safe.
+
+### 🤖 Multi-Backend Support
+Swap between Claude SDK, Codex, and other backends based on the task. Use Claude for complex reasoning, Codex for code generation—Otto routes automatically or lets you choose.
+
+### 💬 Telegram Integration
+Chat with Otto like a friend. Send text, voice messages, or files. Get notifications when background tasks complete. Configure settings through conversation.
+
+### ⏰ Scheduled Tasks & Pipelines
+Schedule one-off tasks or recurring jobs with cron expressions. Chain multiple steps into pipelines with dependencies. Otto runs them in the background and pings you when done.
+
+### 🧠 Session Management
+Conversations are persistent. Fork a session to explore a tangent. Switch between contexts. Pick up where you left off.
+
+### 💾 Memory & Context Persistence
+Otto remembers. Store facts, project context, and preferences in memory. Search and recall across sessions. She gets smarter the more you use her.
+
+## Quick Start
+
+After installing, start Otto:
+
+```bash
+source ~/agent/.venv/bin/activate
+otto service start telegram -f
+```
+
+Open Telegram and message your bot. Otto will help you finish configuring.
+
+**Basic commands:**
+
+```bash
+otto doctor           # Health check
+otto service status   # Show running services
+otto config get       # View configuration
+otto mcp start        # Start MCP Gateway
+```
+
+**Chat-first configuration** — many settings can be changed through conversation:
+
+> "Enable voice transcription"
+> "Switch to Claude backend"
+> "Set my timezone to EST"
+
+⚠️ **API keys & secrets** — always configure via CLI:
+
+```bash
+otto config set backends.claude.api_key "YOUR_API_KEY"
+# Or use ~/.otto/config/.env
+```
+
+## Architecture Overview
+
+```
+┌──────────────────┐
+│   You (Telegram) │
+└────────┬─────────┘
+         ▼
+┌──────────────────┐     ┌─────────────────┐
+│  Telegram Bot    │────▶│   Orchestrator  │
+└──────────────────┘     └────────┬────────┘
+                                  │
+         ┌────────────────────────┼────────────────────────┐
+         ▼                        ▼                        ▼
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Claude SDK    │    │     Codex       │    │    Generic      │
+└────────┬────────┘    └────────┬────────┘    └────────┬────────┘
+         │                      │                      │
+         └──────────────────────┼──────────────────────┘
+                                ▼
+                    ┌───────────────────────┐
+                    │      MCP Gateway      │
+                    │  (Tools & Policies)   │
+                    └───────────────────────┘
+```
+
+- **Telegram Bot** — Your interface. Handles messages, voice, files, notifications.
+- **Orchestrator** — Routes requests, spawns agents, loads context.
+- **Backends** — Pluggable LLM wrappers (Claude SDK, Codex, generic LiteLLM).
+- **MCP Gateway** — Unified tool access with policy-based control.
+- **Memory** — Persistent storage for facts, projects, and conversation context.
+
+## Configuration
+
+Otto stores runtime data in `~/.otto/`:
+
+```
+~/.otto/
+├── brainfile.md      # Identity & personality
+├── config/           # Settings & secrets
+├── memory/           # Knowledge base
+├── sessions/         # Conversation history
+├── skills/           # Custom skills
+└── outputs/          # Background task results
+```
+
+For detailed configuration options, see the [Installation Guide](docs/guide/02-installation.md) and [User Guide](docs/guide/03-user-guide.md).
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Architecture](docs/guide/01-architecture.md) | System overview and components |
+| [Installation](docs/guide/02-installation.md) | Setup instructions |
+| [User Guide](docs/guide/03-user-guide.md) | How to interact with Otto |
+| [Developer Guide](docs/guide/04-developer-guide.md) | Extending Otto |
+| [Operations](docs/guide/05-operations-guide.md) | Running in production |
+
+## Requirements
+
+- Python 3.10+
+- Git
+- Telegram bot token (from [@BotFather](https://t.me/botfather))
+
+**Optional:**
+- Docker (for some MCP servers)
+- Node.js (for agent backend CLIs)
+- ffmpeg (for voice transcription)
+
+## Contributing
+
+Contributions welcome! Whether it's bug fixes, new features, or documentation improvements.
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feature/cool-thing`)
+3. Make your changes
+4. Run tests (`make test`)
+5. Submit a PR
+
+Please keep PRs focused and include tests for new functionality.
+
+## License
+
+MIT — do whatever you want with it.
+
+---
+
+<p align="center">
+  Built with ☕ and questionable life choices.<br>
+  <sub>Otto is a personal project. Use at your own risk, but she's been pretty reliable so far.</sub>
+</p>