Setup & Quickstart #

Morse agents (Dot and Dash) are designed to be run as self-contained Python applications using uv, a fast and reliable Python package manager and project runner.

1. Prerequisites #

Python 3.11+: Ensure you have a modern Python version installed.

uv: If you don't have it, install it via:

curl -LsSf https://astral.sh/uv/install.sh | sh

External CLI Tools:
- Claude Code: Required to run agents using the claude harness.
- Gemini CLI: Required to run agents using the gemini harness.

2. Initial Setup #

Each agent (Dot and Dash) lives in its own directory with its own dependencies and configuration.

For Dot: #

Navigate to the dot/ directory:
```
cd dot
```
Install dependencies:
```
uv sync
```
Configure environment variables:
```
cp .env.example .env
```
Edit .env and provide your DISCORD_TOKEN, BSKY_HANDLE, BSKY_APP_PASSWORD, and optionally GEMINI_API_KEY.

For Dash: #

Navigate to the dash/ directory:
```
cd dash
```
Install dependencies:
```
uv sync
```
Configure environment variables:
```
cp .env.example .env
```
Edit .env and provide your DASH_DISCORD_TOKEN, DASH_BSKY_HANDLE, DASH_BSKY_APP_PASSWORD, and optionally GEMINI_API_KEY.

3. Running the Agents #

There are two primary ways to interact with the agents: the CLI for manual commands and the Orchestrator for continuous operation (Discord + Scheduling).

Using the CLI #

The dot (or dash) command allows you to send messages, trigger checks, or dry-run prompts.

# Send a message to Dot (defaults to Claude harness)
uv run dot say "Hello Dot, what are your current goals?"

# Send a message using the Gemini harness
uv run dot say "Hello Dot" --harness gemini

# Trigger a scheduled-style operational check
uv run dot tick

# View the last 10 journal entries
uv run dot log show

Running the Orchestrator #

The Orchestrator is the long-running process that manages the Discord bridge and the background scheduler.

# Start the Dot orchestrator
uv run dot-coordinator

# Start the Dash orchestrator
uv run dash-coordinator

4. Troubleshooting #

"Module not found": Ensure you are running commands with uv run to use the virtual environment managed by uv.
"Missing Environment Variable": Check that your .env file is in the same directory as the pyproject.toml file (e.g., inside dot/ or dash/).
Discord Bot not responding: Verify your DISCORD_TOKEN and ensure the bot has the necessary Gateway Intents enabled in the Discord Developer Portal (specifically Message Content Intent).

5. Optional: Adding Metacog #

For advanced cognitive capabilities, it is highly recommended to integrate the Metacog MCP server. Metacog provides the agents with structured reasoning and internal metacognitive tools.

To add Metacog:

Get the Server: Follow the installation instructions at the Metacog repository.
Update mcp-config.json: Add the metacog server to the mcpServers object in your agent's mcp-config.json:
```
"metacog": {
  "type": "http",
  "url": "https://metacog.inanna-c38.workers.dev/mcp"
}
```
Update Invocation Scripts: In invoke_dot.py or invoke_dash.py, ensure that mcp__metacog__* is added to the --allowedTools list in the invoke_claude or invoke_gemini functions.