Python on Yarang's Tech Lair

Building a Multi-LLM Distributed Orchestrator with NATS JetStream

Fri, 08 May 2026 21:57:11 +0900

Part 1 discussed the model-specific limitations discovered while running four AIs—Claude, ZAI, Codex, and Gemini—concurrently on the same tasks. This part is about “how we made it possible”—the system design and implementation story.

System Overview

AgentForge consists of three components.

[Task Publisher]
 │ NATS JetStream publish
 ▼
[NATS Broker] ─── af.worker.{id}.inbox
 │ JetStream consume (independent streams per worker)
 ▼
[Worker Pollers] × N (poller.py × 18 instances)
 │ LLM CLI Execution (claude / codex / gemini)
 ▼
[Result Return] af.task.{task_id}.completed

When a publisher posts a task to NATS, each worker, which is independently subscribed, receives the message on its inbox and executes the LLM CLI. The result is then published back to a completion topic.

Why NATS JetStream?

We considered several message broker options: Redis Streams, Kafka, RabbitMQ, and NATS JetStream.

Reasons for choosing NATS JetStream:

Single Binary — Operates with a single nats-server without requiring separate runtimes. It has no dependencies like Kafka’s ZooKeeper or RabbitMQ’s Erlang/OTP.
Built-in Persistence — JetStream is a streaming layer on top of NATS, storing messages to the filesystem. This ensures that unprocessed tasks are not lost even if a worker restarts.
NKey-based Authentication — We can issue independent Ed25519 key pairs for each worker. If one worker is compromised, the credentials of other workers remain valid.
Lightweight — Memory usage is around 30MB on a single server. Even with 18 workers connected, the broker load is minimal.

The Core: Backend Adapter in `poller.py`

The heart of the worker is poller.py. This single file handles NATS subscriptions, LLM CLI execution, and result returns.

Since LLMs have different execution methods, we separated them into a backend adapter dictionary.

_BACKENDS: dict[str, dict] = {
 "claude": {
 "bin": os.environ.get("CLAUDE_BIN", "/usr/local/bin/claude"),
 "tools": os.environ.get("ALLOWED_TOOLS", "Read,Edit,Write,Glob,Grep"),
 "model": os.environ.get("CLAUDE_MODEL", ""),
 },
 "codex": {
 "bin": os.environ.get("CODEX_BIN", "/usr/bin/codex"),
 "model": os.environ.get("CODEX_MODEL", ""),
 "sandbox": os.environ.get("CODEX_SANDBOX", "read-only"),
 },
 "gemini_cli": {
 "bin": os.environ.get("GEMINI_BIN", "/usr/bin/gemini"),
 "model": os.environ.get("GEMINI_MODEL", ""),
 },
}

The MODEL_BACKEND environment variable determines which LLM to use. This allows the same poller.py code to run different LLMs across 18 workers.

Claude Backend

async def run_claude(instructions: str, task_id: str) -> tuple[int, str]:
 cfg = _BACKENDS["claude"]
 cmd = [cfg["bin"], "--print", "--allowedTools", cfg["tools"]]
 if cfg.get("model"):
 cmd += ["--model", cfg["model"]]
 proc = await asyncio.create_subprocess_exec(*cmd, stdin=PIPE, stdout=PIPE, stderr=PIPE)

The --print flag is key. It runs Claude Code in non-interactive mode instead of conversational mode, ensuring the results are returned via stdout.

ZAI Backend

ZAI offers an Anthropic API-compatible endpoint, so it doesn’t require a separate backend. Routing is handled by two environment variables.

# /etc/agentforge/cc-zai-high-dev-01.env
ANTHROPIC_BASE_URL=<ZAI endpoint>
ANTHROPIC_AUTH_TOKEN=<ZAI API key>

By injecting this file using systemd’s EnvironmentFile= directive, the claude binary sends requests to the ZAI endpoint. This allows us to connect to a different LLM provider simply by changing environment variables, without altering the code.

Declarative Management: `fleet.yaml` × `servers.yaml`

Manually managing 18 workers is impractical. We declaratively defined the entire infrastructure using two YAML files.

`servers.yaml` — Server Inventory

servers:
 - name: worker-node-1
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

 - name: broker-host
 role: broker-host
 services: [nats-jetstream, postgres]

 - name: worker-node-2
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

`fleet.yaml` — Worker Placement

workers:
 - worker_id: cc-go-dev-01
 llm: claude-code
 model: claude-sonnet-4-6
 lang: go
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: true

 - worker_id: codex-py-dev-01
 llm: codex
 model: gpt-5.5
 lang: python
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

Changing just the host field moves a worker to a different server. Setting enabled: false stops the deployment script from starting that worker.

Worker Templating System: `provision_worker.py`

Manually writing systemd unit files for each new worker is prone to errors. We automated this using Jinja2 templates and a provisioning script.

Template Structure

templates/
 systemd/
 claude.service.j2 # For claude-code and ZAI alike
 codex.service.j2 # OpenAI Codex
 gemini.service.j2 # Google Gemini CLI

The core part of claude.service.j2:

Environment=MODEL_BACKEND=claude
Environment=CLAUDE_BIN={{ claude_bin }}
{% if claude_model %}
Environment=CLAUDE_MODEL={{ claude_model }}
{% endif %}
{% if env_file %}
EnvironmentFile={{ env_file }}
{% endif %}
Environment=WORK_BASE={{ work_base }}
Environment=WORK_DIR={{ work_base }}/repo
Environment="{{ 'ALLOWED_TOOLS=' + allowed_tools }}"
Environment=CREATE_PR={{ 'true' if create_pr else 'false' }}
{% if create_pr and github_remote %}
Environment=GITHUB_REMOTE={{ github_remote }}
{% endif %}

For ZAI workers, the env_file block is activated, adding the EnvironmentFile. For PR creation workers, github_remote is injected. Other settings use defaults.

`provision_worker.py` Usage

# Preview (no actual deployment)
python3 scripts/provision_worker.py --worker new-worker-id --dry-run

# Actual deployment (including NATS creds issuance)
python3 scripts/provision_worker.py --worker new-worker-id --issue-creds

# Bulk deployment for the entire fleet.yaml
python3 scripts/provision_worker.py --all

Internal operations:

Reads worker entries from fleet.yaml.
Reads target hosts from servers.yaml.
Renders Jinja2 templates.
Deploys /etc/systemd/system/{worker_id}-poller.service via SSH.
Creates the working directory.
Executes systemctl daemon-reload && enable --now.
(Optional) Issues NATS NKey with nsc add user → deploys creds → regenerates auth.conf.

Distributed Hosting: Adding Workers to a Second Server

Running all workers on a single server creates a single point of failure. We added Claude workers to a second host.

The method for workers on the second host to connect to the NATS broker is via an autossh tunnel.

[Unit]
Description=NATS Broker Tunnel
After=network-online.target

[Service]
ExecStart=/usr/bin/autossh -N \
 -L 4222:127.0.0.1:4222 \
 -i /home/ubuntu/.ssh/id_ed25519 \
 broker-host
Restart=always
RestartSec=10

With this configuration active, workers always connect to nats://127.0.0.1:4222. They don’t need to know the broker host’s address. As long as the tunnel is alive, it works the same way from any host.

NATS Credential Operations Experience

NATS NKey management was the most complex part of the implementation.

NATS JetStream’s authentication structure is hierarchical.

Operator (Root Signing Authority)
 └── Account: SYS (System Account)
 └── Account: Services (Worker Account)
 ├── User: cc-dev-01
 ├── User: cc-go-dev-01
 ├── User: codex-py-dev-01
 └── ...

Each worker has an independent User NKey and can publish/subscribe within the permissions scope (af.>, _INBOX.>, $JS.>) of the Services account.

Adding a new worker requires the Operator’s signing key. We initially made the mistake of not backing up this key, leading to its loss. Consequently, we had to regenerate the entire Operator and replace all worker credentials en masse. The service downtime was approximately 60 seconds.

# Regeneration procedure
nsc add operator AgentForge
nsc add account SYS
nsc add account Services
for worker in cc-dev-01 cc-go-dev-01 ...; do
 nsc add user --account Services --name $worker \
 --allow-pub "af.>,_INBOX.>,$JS.>" \
 --allow-sub "af.>,_INBOX.>,$JS.>"
done
nsc generate config --mem-resolver --sys-account SYS > auth.new.conf

Adding a New Worker: The Full Procedure

Since the completion of this system, adding a new worker is straightforward.

Step 1: Add an entry to fleet.yaml

- worker_id: my-new-worker
 llm: claude-code
 model: claude-haiku-4-5
 lang: multi
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

Step 2: Preview

python3 scripts/provision_worker.py --worker my-new-worker --dry-run

Step 3: Actual Deployment

python3 scripts/provision_worker.py --worker my-new-worker --issue-creds

That’s it. Template rendering, SSH deployment, NATS credential issuance, and service registration are all handled by a single command.

Next Steps

The current system is structured such that workers process tasks independently. Future plans include:

Routing Policies: Automatically selecting the appropriate worker based on task characteristics (e.g., Go code → claude-go-dev, cost-first → ZAI lightweight tier).
Results Comparison Dashboard: A UI to display fan-out results side-by-side.
Cost Tracking: Aggregating API call costs per worker.

The code is publicly available on GitHub.

Computer Use API vs Structured Output: Cost-Effective LLM Implementation Strategies

Wed, 06 May 2026 09:00:48 +0900

Computer Use API vs Structured Output: Cost-Effective LLM Implementation Strategies

Recently, I came across an interesting article on Hacker News. It was titled [Computer Use is 45x more expensive than structured APIs]. Anthropic’s latest feature, ‘Computer Use’, allows AI to see the computer screen and manipulate the mouse and keyboard to perform tasks on behalf of the user. It’s quite fascinating, much like an AI inputting combos in the game Tekken for a player.

However, an analysis revealed that the implementation cost of this feature is a staggering 45 times higher than using traditional Structured Output (like JSON mode).

In this post, we’ll analyze why such a gap exists and how we can wisely address this cost issue in our development of Multi-Agent Systems (e.g., ZeroClaw), complete with practical code examples.

1. Analyzing the Cause of the Cost Gap

Computer Use (GUI-Based Approach)

‘Computer Use’ is essentially similar to VNC (RDP) remote control. In each turn, the AI must perform the following:

Screen Capture: Download a high-resolution image. (Leads to a surge in token costs)
Visual Processing: Run a large-scale Vision model to understand the image.
Coordinate Calculation: Calculate the button’s position in pixels.
Action Execution: Send mouse clicks/keyboard inputs.

This process consumes millions of ‘visual tokens’ instead of simple text responses.

Structured Output (API-Based Approach)

On the other hand, the traditional approach we configure through blog API servers or MCP (Model Context Protocol) is far more efficient.

Text Input: System status or user intent is conveyed as text.
Logical Reasoning: The LLM parses the text and makes decisions.
Direct Invocation: Functions are directly executed via tool_use blocks. (No image processing required)

2. Practical Solution: Hybrid Architecture

It’s wasteful to handle every task using Computer Use. We need to apply the ‘Principle of Tool Separation’ learned from projects like ZeroClaw or MCP Blog Automation.

Strategy: Tool Usage Priority

Priority 1: Native API (Structured Output)
- Tasks with clear logic, such as database lookups, API calls, and file creation, should always be handled by function calls.
Priority 2: Browser Automation (Playwright/Selenium)
- For complex DOM manipulation where no backend API exists. (Parsing an HTML tree is cheaper than image processing)
Last Resort: Computer Use (Vision)
- Targeted only for situations with screen captures or legacy software where DOM access is impossible, such as video editing programs.

3. Code Example: Implementing a Cost-Optimized Agent

Let’s create a Python example that allows an LLM to selectively use API calls (Structured) and browser control (Browser). Since Computer Use is still tied to specific cloud environments, we’ll introduce code that compares the most realistic alternatives: Playwright (HTML-based) and API calls.

Scenario: Automating Blog Post Publication

Let’s assume we ask an LLM agent to “Summarize the latest tech news and publish it to my blog.”

Structured Approach (Structured Output + API)

import json
from typing import Literal

# 1. Tool Definitions (API Approach)
tools = [
 {
 "type": "function",
 "function": {
 "name": "create_blog_post",
 "description": "Publishes a new post to the blog. (Cheapest and fastest)",
 "parameters": {
 "type": "object",
 "properties": {
 "title": {"type": "string"},
 "content": {"type": "string"},
 "tags": {"type": "array", "items": {"type": "string"}}
 },
 "required": ["title", "content"]
 }
 }
 },
 {
 "type": "function",
 "function": {
 "name": "search_web_browser",
 "description": "Controls the web browser to search for information. (Use when no API is available)",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string"}
 },
 "required": ["query"]
 }
 }
 }
]

# 2. Agent Execution Logic (Simulation)
def run_agent(user_query: str):
 # Step 1: LLM requests tool usage (in reality, this is an OpenAI/Anthropic API call)
 # Simulating LLM response: Selecting the create_blog_post tool
 llm_response = {
 "tool": "create_blog_post",
 "arguments": {
 "title": "Gemma 4 Acceleration Techniques",
 "content": "Google's latest model, Gemma, through multi-token prediction...",
 "tags": ["AI", "Google"]
 }
 }

 # Step 2: Local function execution (no vision needed)
 if llm_response['tool'] == 'create_blog_post':
 print(f"[API Execution] Publishing blog post: {llm_response['arguments']['title']}")
 # In reality, this would be a requests.post('https://blog-api.com/posts', ...) call
 return {"status": "success", "cost": "0.0001 USD"}

print(run_agent("Write a blog post for me."))

This method is very inexpensive as it only exchanges text.

Unstructured Approach (Computer Use Simulation - Increased Cost)

Imagine if we bypassed the blog API and used Computer Use to open a web browser and write the post.

# Pseudocode for Computer Use approach (cost explosion area)
def run_computer_use_agent():
 # 1. Screen Capture (1024x768 image -> approx. 1,100 tokens consumed)
 screenshot = capture_screen()
 print(f"[Vision] Analyzing screen... (1,100 tokens consumed)")

 # 2. LLM Inference: "Find the login button"
 action = llm_vision_inference(screenshot, prompt="Find the login button")
 # Result: {"x": 500, "y": 300, "action": "click"}
 print(f"[Action] Moving mouse and clicking: {action}")

 # 3. Capture screen again and analyze input fields
 screenshot = capture_screen()
 print(f"[Vision] Analyzing input fields... (1,100 tokens consumed)")
 
 # ... (Repetitive capture and inference)
 return {"status": "success", "cost": "0.05 USD"} 
 # Potential cost increase of ~500x compared to API approach (0.0001 USD)

4. ZeroClaw and MCP Architecture Application Guide

Applying this principle to our ongoing projects like ZeroClaw (high-performance Rust agent) or Discord MCP leads to the following design.

Adherence to MCP (Model Context Protocol) Standard:
- Expose all possible resources (file system, databases, cloud resources) to the MCP Server, allowing LLMs to control them via Structured JSON.
- Example: When sending a Discord message, guide the LLM to call discord_mcp.send_message() instead of opening a browser.
Prompt Engineering:
- Clearly declare in the system prompt.
- “You should call tools instead of looking at the screen. To fulfill user requests, first check the available_tools list and prioritize checking for function calls.”
Fallback Mechanism:
- Create a two-stage structure that wakes up the ‘Computer Use’ or ‘Browser Automation’ agent only when the MCP Server or API is down, or when visual confirmation is absolutely necessary.

5. Conclusion

When developing AI agents, ‘Computer Use’ is like a ‘Swiss Army knife’. It can do everything, but if you pull out the large knife (capture the screen) to tighten a single screw, the cost becomes immense.

We must use the right tool for the right job. For most tasks, we should opt for Structured Output (API), and only resort to Vision/GUI functions when absolutely unavoidable. This strategy allows us to turn the 45x cost difference into our advantage.

We will prioritize this cost-effectiveness as a guiding principle in the communication protocol design for the upcoming ZeroClaw project.

[blog-api-server] Monitoring Dashboard and Alerting System

Tue, 03 Mar 2026 14:53:47 +0900

[blog-api-server] Monitoring Dashboard and Alerting System

Overview

A Prometheus-based monitoring system and Slack/Email alerting have been added to blog-api-server, enabling real-time server status tracking and immediate response to issues.

Monitoring Architecture

flowchart TB
 A[HTTP Request] --> B[MonitoringMiddleware]
 B --> C[Request Logging]
 B --> D[PrometheusMiddleware]
 D --> E[Metrics Collection]
 C --> F[AlertManager]
 E --> F
 F --> G{Threshold Check}
 G -->|Over Threshold| H[Slack Webhook]
 G -->|Critical| I[Email Alert]
 G -->|Normal| J[Log Only]
 K[Prometheus Server] --> L[/metrics/prometheus]
 M[Dashboard] --> N[/dashboard]

Prometheus Metrics

Basic HTTP Metrics

Metric	Type	Labels	Description
`http_requests_total`	Counter	method, endpoint, status	Total HTTP requests
`http_request_duration_seconds`	Histogram	method, endpoint	Request latency distribution
`http_errors_total`	Counter	method, endpoint, status	Total error count
`active_requests`	Gauge	-	Current active requests

Business Metrics

Metric	Type	Labels	Description
`git_operations_total`	Counter	operation, status	Git operation count
`git_operation_duration_seconds`	Histogram	operation	Git operation duration
`translation_requests_total`	Counter	source_lang, target_lang, status	Translation request count
`translation_duration_seconds`	Histogram	-	Translation duration
`post_operations_total`	Counter	operation, language, status	Post operation count

Metrics Collection Code

# prometheus_exporter.py
from prometheus_client import Counter, Histogram, Gauge

http_requests_total = Counter(
 'http_requests_total',
 'Total HTTP requests',
 ['method', 'endpoint', 'status']
)

http_request_duration_seconds = Histogram(
 'http_request_duration_seconds',
 'HTTP request latency',
 ['method', 'endpoint']
)

# Auto-collection in middleware
class PrometheusMiddleware(BaseHTTPMiddleware):
 async def dispatch(self, request: Request, call_next):
 start_time = time.time()
 response = await call_next(request)
 duration = time.time() - start_time

 http_requests_total.labels(
 method=request.method,
 endpoint=request.url.path,
 status=response.status_code
 ).inc()

 http_request_duration_seconds.labels(
 method=request.method,
 endpoint=request.url.path
 ).observe(duration)

Alerting System

Alert Rules

Rule Name	Condition	Severity	Cooldown
High Error Rate	error_rate > 5%	WARNING	5 min
Critical Error Rate	error_rate > 20%	CRITICAL	1 min
Slow Response Time	avg_response_time > 2000ms	WARNING	10 min
High Slow Request Rate	slow_request_rate > 10%	WARNING	5 min

Alert Channels

Slack Webhook

Supports all severity levels
Color-coded severity (INFO: green, WARNING: orange, ERROR: red, CRITICAL: dark red)

Email

CRITICAL level only
SMTP-based email delivery

AlertManager Code

# alerting.py
class AlertManager:
 def check_and_alert(self, metrics: Dict[str, Any]):
 for rule in self.rules:
 if rule.should_trigger(metrics):
 self._send_alert(rule, metrics)

 def _send_alert(self, rule: AlertRule, metrics: Dict[str, Any]):
 message = f"""
Alert Rule: {rule.name}
Condition: {rule.condition}

Current Metrics:
- Total Requests: {metrics.get('total_requests', 0)}
- Error Count: {metrics.get('error_count', 0)}
- Error Rate: {metrics.get('error_rate_percent', 0)}%
- Slow Requests: {metrics.get('slow_request_count', 0)}
"""
 self.slack.send(
 title=f"Alert: {rule.name}",
 message=message.strip(),
 severity=rule.severity
 )

Dashboard Configuration

Monitoring Endpoints

Path	Auth	Description
`/health`	Not Required	Server health check
`/metrics`	Required	JSON format metrics
`/metrics/prometheus`	Not Required	Prometheus format metrics
`/metrics/reset`	Required	Reset metrics
`/dashboard`	Not Required	Web dashboard
`/alerts/rules`	Required	Alert rules list
`/alerts/send`	Required	Manual alert send

Request Tracking Middleware

# middleware.py
class MonitoringMiddleware(BaseHTTPMiddleware):
 async def dispatch(self, request: Request, call_next):
 request_id = str(uuid.uuid4())
 start_time = time.time()

 response = await call_next(request)
 process_time = (time.time() - start_time) * 1000

 # Add tracking info to response headers
 response.headers["X-Process-Time"] = f"{process_time:.2f}"
 response.headers["X-Request-ID"] = request_id

 return response

Environment Variables

# Slack Alerts
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

# Email Alerts
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
ALERT_FROM_EMAIL=your-email@gmail.com
ALERT_TO_EMAILS=admin@example.com,ops@example.com

# Threshold Settings
SLOW_REQUEST_THRESHOLD=1000 # 1 second
VERY_SLOW_THRESHOLD=3000 # 3 seconds
MAX_BODY_LOG_LENGTH=1000

Future Plans

Grafana Integration: Visualize Prometheus data in Grafana dashboard
Dynamic Alert Rules: API to add/remove alert rules at runtime
Metrics Retention: Long-term metrics storage and analysis
Enhanced Health Checks: Dependency service (Git, LLM) status checks

Conclusion

With Prometheus-based monitoring and Slack/Email alerting, infrastructure is now in place for real-time server monitoring and immediate incident response.

Korean Version: 한국어 버전

[Discord Decision MCP] Architecture Design Document

Mon, 02 Mar 2026 21:36:30 +0900

Discord Decision MCP — Architecture Design Document

1. Project Overview

1.1 Purpose

An MCP (Model Context Protocol) server that allows Claude Code, while operating in tmux Teammate mode for autonomous work, to ask questions via Discord when user decisions are needed and resume work after receiving responses.

1.2 Key Features

Feature	Description
One Bot per Project	Each project uses an independent Discord Bot
Infinite Wait Default	Wait for user response without timeout (Claude must not proceed unilaterally)
State Persistence	Restore waiting state after process restart
Korean-Friendly	Korean options, Yes/No response support
MCP-Based Communication	All Discord communication through MCP Tools

1.3 Version Information

Version: 1.0.0
Python Requirement: >= 3.11
MCP Framework: FastMCP >= 0.1.0

2. Directory Structure

discord-decision/
├── discord_mcp/ # Main package
│ ├── __init__.py
│ ├── server.py # MCP server entry point
│ ├── config.py # Environment variable configuration
│ │
│ ├── bot/ # Discord API client
│ │ ├── __init__.py
│ │ ├── client.py # REST API client (httpx)
│ │ └── gateway.py # WebSocket gateway (receive only)
│ │
│ ├── decision/ # Decision request management
│ │ ├── __init__.py
│ │ ├── manager.py # Decision request lifecycle management
│ │ ├── poller.py # Discord polling and response waiting
│ │ ├── parser.py # User response parsing
│ │ └── state.py # State persistence (JSON files)
│ │
│ ├── tools/ # MCP Tools implementation
│ │ ├── __init__.py
│ │ ├── ask.py # discord_ask_decision
│ │ ├── notify.py # discord_notify
│ │ ├── report.py # discord_report_progress
│ │ ├── status.py # discord_check_pending
│ │ ├── inbox.py # discord_read_inbox, discord_clear_inbox
│ │ └── _templates.py # Discord message templates
│ │
│ └── daemon/ # Watcher daemon
│ ├── __init__.py
│ ├── watcher.py # Discord channel monitoring (discord-watch CLI)
│ └── inbox.py # Inbox file management
│
├── scripts/ # Utility scripts
│ └── start-discord-watch.sh
│
├── tests/ # Test suite
│ ├── __init__.py
│ ├── test_parser.py
│ └── test_state.py
│
├── CLAUDE.md # Claude Code project instructions
├── README.md # Project description
├── pyproject.toml # Project configuration and dependencies
└── mcp.json.example # MCP configuration example

3. Key Module Descriptions

3.1 Server Entry Point (`server.py`)

Role: FastMCP server creation and MCP Tool registration

mcp = FastMCP(name="discord-decision-mcp")
# Tool registration
mcp.tool()(discord_ask_decision)
mcp.tool()(discord_notify)
mcp.tool()(discord_report_progress)
mcp.tool()(discord_check_pending)
mcp.tool()(discord_read_inbox)
mcp.tool()(discord_clear_inbox)

Execution:

discord-mcp # or python -m discord_mcp.server

3.2 Configuration Management (`config.py`)

Role: Load configuration values from environment variables

Environment Variable	Description	Default
`DISCORD_BOT_TOKEN`	Discord Bot Token (includes “Bot " prefix)	Required
`DISCORD_CHANNEL_ID`	Default question channel ID	Required
`PROJECT_NAME`	Used for question_id generation	“project”
`PENDING_DIR`	State file storage path	`~/.claude/pending_decisions`
`POLL_INTERVAL_SECONDS`	Discord polling interval (seconds)	5

3.3 Discord API Client (`bot/`)

3.3.1 REST API Client (`client.py`)

Role: Discord REST API calls (httpx-based)

Key Methods:

class DiscordClient:
 async def send_message(channel_id, content, embeds=None)
 async def get_messages(channel_id, after=None, limit=50)
 async def create_thread(channel_id, name, first_message)
 async def archive_thread(thread_id)

Features:

Automatic rate limit handling (retry on 429 response)
Singleton pattern (get_client())

3.3.2 WebSocket Gateway (`gateway.py`)

Role: Discord Gateway WebSocket connection (receive only)

Features:

Real-time MESSAGE_CREATE event reception
Reduces polling delay from 5 seconds to instant
System works without Gateway (polling fallback)
Automatic reconnection (Exponential backoff)

class GatewayClient:
 async def run() # Start event reception
 async def stop() # Close connection

3.4 Decision Request Management (`decision/`)

3.4.1 DecisionManager (`manager.py`)

Role: Coordinate the entire lifecycle of decision requests

class DecisionManager:
 async def ask(question, context, options, timeout_seconds, thread_id) -> PollResult
 async def restore_pending() -> list[DecisionState]

Flow:

Check for duplicate questions
Create thread (or reuse existing thread)
Create state file (~/.claude/pending_decisions/{question_id}.json)
Run poller to wait for response
Mark disconnected state on SIGHUP signal

3.4.2 DecisionPoller (`poller.py`)

Role: Poll Discord channel and wait for response

class DecisionPoller:
 async def wait(state: DecisionState) -> PollResult

Features:

Default: infinite wait (timeout_seconds=None)
Real-time waiting status display in tmux pane (ANSI escape)
Re-question up to 2 times for ambiguous responses

3.4.3 Response Parser (`parser.py`)

Role: Parse user Discord responses

Supported Patterns:

Option matching: “A”, “a”, “A번”, “A로 해줘”, “1”, “1번”
Affirmative/Negative: “yes”, “네”, “예”, “no”, “아니요”
Natural language: 15+ characters or 3+ Korean characters

def parse_response(text: str, options: list[str]) -> ParseResult
def build_clarify_message(...) -> str # Generate re-question message

3.4.4 State Store (`state.py`)

Role: Persist decision request state to JSON files

State File Location: ~/.claude/pending_decisions/{question_id}.json

class DecisionState(BaseModel):
 question_id: str
 project: str
 question: str
 context: str
 options: list[str]
 timeout_seconds: float | None
 thread_id: str
 message_id: str
 asked_at: str
 status: Literal["pending", "disconnected", "resolved", "aborted", "timeout"]
 clarify_attempts: int
 resolved_at: str | None
 resolution: str | None
 selected_option: str | None

class StateStore:
 def save(state: DecisionState)
 def load(question_id: str) -> DecisionState | None
 def load_all_pending() -> list[DecisionState]
 def resolve(question_id, resolution, selected_option)
 def is_duplicate(question: str) -> bool

3.5 MCP Tools (`tools/`)

Tool	Blocking	Description
`discord_ask_decision`	✅	User decision request
`discord_notify`	❌	Progress notification
`discord_report_progress`	❌	Task completion report
`discord_check_pending`	❌	Check pending questions
`discord_read_inbox`	❌	Inbox message query
`discord_clear_inbox`	❌	Inbox message deletion

3.6 Watcher Daemon (`daemon/`)

3.6.1 DiscordWatcher (`watcher.py`)

Role: Monitor Discord channel and record new messages to inbox file

Execution:

discord-watch --interval 10
# or
tmux new-session -d -s discord-watch 'uv run discord-watch'

Features:

Periodically poll specified channel(s)
Record new user messages to inbox
Display status in tmux pane

3.6.2 InboxStore (`inbox.py`)

Role: JSON file-based storage for Discord messages

Inbox File Location: ~/.claude/discord_inbox.json

class InboxMessage:
 message_id: str
 channel_id: str
 thread_id: str | None
 author: str
 author_id: str
 content: str
 timestamp: str
 read: bool

class InboxStore:
 def add_message(msg: InboxMessage)
 def get_unread() -> list[InboxMessage]
 def mark_read(message_id: str)
 def clear_read() # Delete read messages

4. Data Flow Diagrams

4.1 Decision Request Flow

┌─────────────────┐
│ Claude Code │
└────────┬────────┘
 │ discord_ask_decision()
 ▼
┌─────────────────────────────────────┐
│ MCP Server (server.py) │
│ ┌───────────────────────────────┐ │
│ │ DecisionManager.ask() │ │
│ │ 1. Duplicate check │ │
│ │ 2. Thread creation │ │
│ │ 3. State file save │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 ▼
┌─────────────────────────────────────┐
│ DecisionPoller.wait() │
│ ┌───────────────────────────────┐ │
│ │ Polling loop │ │
│ │ 1. tmux status update │ │
│ │ 2. Discord API call │ │
│ │ 3. Response parsing │ │
│ │ 4. Re-question if ambiguous │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 │
 ┌─────────┴─────────┐
 ▼ ▼
┌───────────────────┐ ┌──────────────────┐
│ Discord REST API │ │ Discord Thread │
│ (client.py) │ │ │
└───────────────────┘ └────────┬─────────┘
 │
 ┌────────▼────────┐
 │ User Response │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ parser.py │
 │ - Option match │
 │ - Ambiguity │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ store.resolve()│
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ PollResult │
 │ Return │
 └─────────────────┘

4.2 Watcher Daemon Flow

┌─────────────────────────────────────────────┐
│ DiscordWatcher (daemon/watcher.py) │
│ ┌───────────────────────────────────────┐ │
│ │ 1. Set initial message ID │ │
│ │ 2. Periodic polling (default 10s) │ │
│ │ 3. Detect new messages │ │
│ │ 4. InboxStore.add_message() │ │
│ └───────────────────┬───────────────────┘ │
└──────────────────────┼──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ ~/.claude/discord_inbox.json │
│ { │
│ "last_message_id": "...", │
│ "messages": [ │
│ { "message_id": "...", ... } │
│ ] │
│ } │
└──────────────────────┬──────────────────────┘
 ▲
 │ discord_read_inbox()
┌──────────────────────┴──────────────────────┐
│ Claude Code │
└─────────────────────────────────────────────┘

4.3 Session Restoration Flow

┌─────────────────────────────────────────────┐
│ Claude Code session start │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ discord_check_pending() │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ DecisionManager.restore_pending() │
│ ┌───────────────────────────────────────┐ │
│ │ 1. ~/.claude/pending_decisions/*.json │ │
│ │ 2. Check Thread via Discord API │ │
│ │ 3. If answered → Auto-resolve │ │
│ │ 4. If no answer → Restart notification│ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

5. MCP Tools List

5.1 discord_ask_decision

Description: Send question to Discord Thread and wait for response when user decision is needed (blocking)

Parameters:

Name	Type	Required	Description
`question`	string	✅	Question content
`context`	string	✅	Current work context
`options`	string[]	❌	List of options (empty array for free response)
`timeout_seconds`	float	❌	Wait timeout (null for infinite wait)
`thread_id`	string	❌	Existing Thread ID (null to create new Thread)

Return Value:

{
 "success": true,
 "answer": "A) Execute now",
 "selected_option": "A) Execute now",
 "question_id": "project_20260301_abc123",
 "timed_out": false,
 "aborted": false
}

5.2 discord_notify

Description: Send progress notification to Discord (non-blocking)

Parameters:

Name	Type	Required	Description
`message`	string	✅	Notification message
`level`	string	❌	info/warning/success/error (default: info)
`thread_id`	string	❌	Thread ID to send to (null for default channel)

5.3 discord_report_progress

Description: Report task completion or milestone completion (non-blocking)

Parameters:

Name	Type	Required	Description
`title`	string	✅	Report title
`summary`	string	✅	Task result summary
`details`	string[]	❌	List of detail items
`thread_id`	string	❌	Thread ID to send to

5.4 discord_check_pending

Description: Check pending questions at session start (non-blocking)

Parameters: None

Return Value:

{
 "has_pending": true,
 "pending_questions": [
 {
 "question_id": "project_20260301_abc123",
 "question": "Deploy?",
 "thread_id": "1234567890",
 "asked_at": "2026-03-01T10:30:00Z",
 "status": "pending"
 }
 ]
}

5.5 discord_read_inbox

Description: Query messages stored in Inbox (non-blocking)

Parameters:

Name	Type	Default	Description
`unread_only`	boolean	true	Return only unread messages
`mark_read`	boolean	false	Mark queried messages as read

5.6 discord_clear_inbox

Description: Delete Inbox messages (non-blocking)

Parameters:

Name	Type	Default	Description
`read_only`	boolean	true	Delete only read messages

6. Dependency Information

6.1 Core Dependencies

Package	Version	Purpose
`fastmcp`	>= 0.1.0	MCP server framework
`httpx`	>= 0.27.0	Async HTTP client
`websockets`	>= 12.0	WebSocket client
`python-dotenv`	>= 1.0.0	Environment variable loading
`pydantic`	>= 2.0.0	Data model validation
`anyio`	>= 4.0.0	Async execution

6.2 Development Dependencies

Package	Purpose
`pytest`	Test framework
`pytest-asyncio`	Async test support
`pytest-mock`	Mock support
`respx`	httpx mocking

6.3 CLI Commands

discord-mcp # Run MCP server
discord-watch # Run watcher daemon

7. State File Format

7.1 Decision State File

Location: ~/.claude/pending_decisions/{question_id}.json

{
 "question_id": "project_20260301_abc123",
 "project": "my-project",
 "question": "Run DB migration?",
 "context": "v1→v2 schema change",
 "options": ["A) Execute now", "B) Staging first", "C) Hold"],
 "timeout_seconds": null,
 "thread_id": "1234567890",
 "message_id": "0987654321",
 "asked_at": "2026-03-01T10:30:00Z",
 "status": "pending",
 "clarify_attempts": 0,
 "resolved_at": null,
 "resolution": null,
 "selected_option": null
}

7.2 Inbox File

Location: ~/.claude/discord_inbox.json

{
 "last_message_id": "1234567890",
 "messages": [
 {
 "message_id": "1234567890",
 "channel_id": "1234567890",
 "thread_id": null,
 "author": "username",
 "author_id": "1234567890",
 "content": "Message content",
 "timestamp": "2026-03-01T00:00:00Z",
 "read": false
 }
 ]
}

8. Architecture Principles

8.1 Design Principles

Singleton Pattern: DiscordClient, StateStore, InboxStore are module-level singletons
State Persistence: All decision request states are persisted to files
Infinite Wait Default: Timeout default is None so Claude does not proceed unilaterally
Re-question Limit: Ambiguous responses are re-asked up to 2 times
Rate Limit Handling: Automatic wait and retry on Discord API 429 responses

8.2 Error Handling

Situation	Handling
Discord API 429	Automatic wait and retry (max 5 times)
WebSocket disconnection	Reconnect with exponential backoff
Response parsing failure	Re-question up to 2 times then abort
Timeout occurrence	Send abort notification and set aborted state
Session disconnect (SIGHUP)	Save as disconnected state

Document Version: 1.0.0 Last Modified: 2026-03-02

Korean Version: 한국어 버전

[blog-api-server] Logging Improvement Complete

Fri, 27 Feb 2026 23:48:07 +0900

API Server Logging Improvement Complete

Overview

Detailed logging has been added to the blog API server to track request processing.

Added Logging

API Level (`[API]` prefix)

Request start/end
Request parameters
Processing time

Blog Manager Level (`[BLOG_MANAGER]` prefix)

Git lock acquire/release
Sync progress
Filename generation
File writing
Git commit/push step-by-step progress

Git Command Level (`[GIT]` prefix)

Git command execution start
Command completion time
Error and warning messages

Fixed Issues

LogRecord Reserved Attribute Conflict: Changed reserved words like filename, message to post_filename, commit_msg
Deadlock Issue: Removed duplicate lock acquisition in commit_and_push
Path Error: Fixed Korean post path to content/post/

Timing Analysis Example

Git pull: ~2.3s
File write: ~1ms
Git commit: ~42ms
Git push: ~2.5s
Total request time: ~4.8s

Conclusion

With detailed logging, each step of API requests can now be clearly tracked, making it easier to identify issues when they occur.

Korean Version: 한국어 버전

Python on Yarang's Tech Lair

Building a Multi-LLM Distributed Orchestrator with NATS JetStream

System Overview

Why NATS JetStream?

The Core: Backend Adapter in poller.py

Claude Backend

ZAI Backend

Declarative Management: fleet.yaml × servers.yaml

servers.yaml — Server Inventory

fleet.yaml — Worker Placement

Worker Templating System: provision_worker.py

Template Structure

provision_worker.py Usage

Distributed Hosting: Adding Workers to a Second Server

NATS Credential Operations Experience

Adding a New Worker: The Full Procedure

Next Steps

Computer Use API vs Structured Output: Cost-Effective LLM Implementation Strategies

Computer Use API vs Structured Output: Cost-Effective LLM Implementation Strategies

1. Analyzing the Cause of the Cost Gap

Computer Use (GUI-Based Approach)

Structured Output (API-Based Approach)

2. Practical Solution: Hybrid Architecture

Strategy: Tool Usage Priority

3. Code Example: Implementing a Cost-Optimized Agent

Scenario: Automating Blog Post Publication

Structured Approach (Structured Output + API)

Unstructured Approach (Computer Use Simulation - Increased Cost)

4. ZeroClaw and MCP Architecture Application Guide

5. Conclusion

[blog-api-server] Monitoring Dashboard and Alerting System

[blog-api-server] Monitoring Dashboard and Alerting System

Overview

Monitoring Architecture

Prometheus Metrics

Basic HTTP Metrics

Business Metrics

Metrics Collection Code

Alerting System

Alert Rules

Alert Channels

AlertManager Code

Dashboard Configuration

Monitoring Endpoints

Request Tracking Middleware

Environment Variables

Future Plans

Conclusion

[Discord Decision MCP] Architecture Design Document

Discord Decision MCP — Architecture Design Document

1. Project Overview

1.1 Purpose

1.2 Key Features

1.3 Version Information

2. Directory Structure

3. Key Module Descriptions

3.1 Server Entry Point (server.py)

3.2 Configuration Management (config.py)

3.3 Discord API Client (bot/)

3.3.1 REST API Client (client.py)

3.3.2 WebSocket Gateway (gateway.py)

3.4 Decision Request Management (decision/)

3.4.1 DecisionManager (manager.py)

3.4.2 DecisionPoller (poller.py)

3.4.3 Response Parser (parser.py)

3.4.4 State Store (state.py)

3.5 MCP Tools (tools/)

3.6 Watcher Daemon (daemon/)

3.6.1 DiscordWatcher (watcher.py)

3.6.2 InboxStore (inbox.py)

4. Data Flow Diagrams

4.1 Decision Request Flow

4.2 Watcher Daemon Flow

4.3 Session Restoration Flow

5. MCP Tools List

5.1 discord_ask_decision

5.2 discord_notify

5.3 discord_report_progress

5.4 discord_check_pending

5.5 discord_read_inbox

The Core: Backend Adapter in `poller.py`

Declarative Management: `fleet.yaml` × `servers.yaml`

`servers.yaml` — Server Inventory

`fleet.yaml` — Worker Placement

Worker Templating System: `provision_worker.py`

`provision_worker.py` Usage

3.1 Server Entry Point (`server.py`)

3.2 Configuration Management (`config.py`)

3.3 Discord API Client (`bot/`)

3.3.1 REST API Client (`client.py`)

3.3.2 WebSocket Gateway (`gateway.py`)

3.4 Decision Request Management (`decision/`)

3.4.1 DecisionManager (`manager.py`)

3.4.2 DecisionPoller (`poller.py`)

3.4.3 Response Parser (`parser.py`)

3.4.4 State Store (`state.py`)

3.5 MCP Tools (`tools/`)

3.6 Watcher Daemon (`daemon/`)

3.6.1 DiscordWatcher (`watcher.py`)

3.6.2 InboxStore (`inbox.py`)

API Level (`[API]` prefix)

Blog Manager Level (`[BLOG_MANAGER]` prefix)

Git Command Level (`[GIT]` prefix)