Ai on Yarang's Tech Lair

RubyLLM: A Guide to an Integrated AI Interface for Rails

Thu, 25 Jun 2026 09:01:07 +0900

RubyLLM: A Guide to an Integrated AI Interface for Rails

Recently, integrating AI capabilities into applications has become a necessity, not an option. However, calling APIs from various providers like OpenAI, Anthropic, and Google individually increases code complexity and makes maintenance difficult. Fortunately, tools like RubyLLM, which recently gained traction on Hacker News, are emerging to provide an integrated AI development environment within the Ruby and Rails ecosystem.

In this post, we will explore how to use RubyLLM to manage major LLM providers with a single interface in your Ruby on Rails applications and apply it in practice.

What is RubyLLM?

RubyLLM is a lightweight AI client library usable within the Ruby and Rails frameworks. The core strength of this library lies in its ‘Provider Agnostic’ design. Developers can flexibly call various AI models through the standardized methods provided by RubyLLM, without being dependent on specific vendor SDKs.

Key features include:

Support for Multiple Providers: Manage major models like OpenAI (GPT), Anthropic (Claude), and Google (Gemini) with a single gem.
Rails-Friendly: Offers APIs following familiar patterns like ActiveRecord.
Streaming Support: Built-in streaming interface for real-time response generation.

Project Setup

First, add RubyLLM to your Gemfile and install it. (Assuming the latest version)

# Gemfile
gem 'ruby_llm'

After bundling and installing, set up your API keys using environment variables. It is recommended to use Rails’ credentials.yml.enc or a .env file.

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

Basic Usage: Chat Interface

RubyLLM allows for very intuitive implementation of basic text generation tasks. Here’s an example of calling an LLM within a Rails controller or service object.

1. Calling OpenAI GPT-4o

require 'ruby_llm'

# Initialize client
client = RubyLLM::Client.new

response = client.chat(
 model: "gpt-4o",
 messages: [
 { role: "system", content: "You are a friendly assistant." },
 { role: "user", content: "Please explain the main features of the Rust programming language." }
 ]
)

puts response.content
# => "Rust is a systems programming language designed for memory safety, high performance, and safe concurrency..."

2. Easy Model Switching (Preventing Vendor Lock-in)

If business requirements change and you need to switch from OpenAI to Google’s Gemini, you only need to change the model name and API key. The code structure remains the same.

# Maintain existing code, only change model name
gemini_response = client.chat(
 model: "gemini-1.5-pro",
 messages: [
 { role: "system", content: "You are a technical blogger." },
 { role: "user", content: "Summarize the ZeroClaw architecture." }
 ]
)

Practical Application: Implementing Streaming Responses

For a better user experience (UX), a streaming approach, where responses are displayed in real-time as if being typed, is preferred over waiting for the entire generated AI answer at once. RubyLLM makes this easy to implement using blocks (Procs).

Here’s an example of a service class that uses Rails’ Turbo Stream to output text to the screen in real-time.

# app/services/ai_streaming_service.rb
class AiStreamingService
 def initialize(user_message)
 @user_message = user_message
 end

 def call
 client = RubyLLM::Client.new
 
 # OpenAI streaming call
 client.chat(
 model: "gpt-4o-mini",
 messages: [{ role: "user", content: @user_message }],
 stream: proc { |chunk| 
 # Process the received text chunk
 # Example: Broadcast to the client via Rails channel
 ActionCable.server.broadcast "ai_channel", { content: chunk }
 
 # Or print to logs
 print chunk
 $stdout.flush
 }
 )
 end
end

Using this pattern, the LLM can send tokens to the client browser immediately as they are generated, providing a smooth experience similar to using ChatGPT.

Conclusion: AI Development Trends in the Ruby Ecosystem

In the past, Ruby was sometimes seen as lagging behind Python in the AI development domain. However, the emergence of frameworks like RubyLLM demonstrates that Ruby still holds strong competitiveness in building applications that utilize AI models, rather than ‘developing AI models themselves’.

Especially for implementing the agent runtime that our team (ZeroClaw) is pursuing, combining Ruby’s high productivity with RubyLLM’s flexible abstraction layer will allow for faster prototyping and building of complex multi-agent systems.

Just as LangChain or LlamaIndex have become popular in the Python ecosystem, RubyLLM has a high probability of becoming the standard in the Ruby ecosystem. If you are a Rails developer, we recommend applying this tool in a test project, even if it’s just for practice.

Resources

RubyLLM GitHub Repository (Fictional link)
OpenAI API Documentation
Google Gemini API Documentation

Building an MCP Server with Rust: Utilizing the ZeroClaw Architecture

Tue, 09 Jun 2026 09:00:48 +0900

Building an MCP Server with Rust: Utilizing the ZeroClaw Architecture

Recently, Model Context Protocol (MCP) has become a standard interface in the AI agent ecosystem. When building an MCP server in high-performance runtime environments like our team’s ZeroClaw project, Rust’s safety and speed are essential. In this post, we will design a practical, ready-to-implement Rust-based MCP server structure and explore how to build it with actual code.

1. Core Requirements of an MCP Server

To allow AI models to access data, an MCP server must perform the following three core functions:

Resource Discovery: Provide a list of data (files, APIs, etc.) that the model can use.
Resource Access: Efficiently return the actual content of requested data.
Tool Execution: Perform actions within the system based on the model’s instructions.

Rust is ideal for MCP servers handling large-scale requests, especially due to its Zero-cost abstractions and robust asynchronous runtime (tokio).

2. Architecture Design: ZeroClaw Style

Beyond simple RPC calls, we adopt an event-driven architecture for scalability. The structure is as follows:

Transport Layer: Sending and receiving messages via stdio or WebSocket (JSON-RPC 2.0)
Handler Layer: Layer for routing and validating requests
Core Logic: Actual business logic (file system access, DB queries, etc.)

3. Practical Code Examples

We will write a simple MCP server based on stdio (standard input/output), the most common transport. This example implements functionality to allow an LLM to read logs from the local file system.

3.1. Dependency Setup (`Cargo.toml`)

We add crates for serialization and asynchronous processing to leverage Rust’s ecosystem.

[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
async-trait = "0.1"

3.2. Handler Trait Definition

Following the MCP standard, we define a common interface for handling Tool and Resource. This makes it easier to integrate with the ZeroClaw runtime later.

use serde_json::Value;
use async_trait::async_trait;

#[async_trait]
pub trait McpHandler {
 async fn handle(&self, params: Value) -> Result<Value, String>;
 fn name(&self) -> &str;
}

3.3. Implementing the Log Reading Tool

Now, we implement the logic to actually read files within the server and provide them to the AI model.

use std::fs;
use std::path::Path;

pub struct LogReaderTool;

#[async_trait]
impl McpHandler for LogReaderTool {
 fn name(&self) -> &str {
 "read_logs"
 }

 async fn handle(&self, params: Value) -> Result<Value, String> {
 // 1. Parameter validation and extraction
 let file_path = params.get("path")
 .and_then(|v| v.as_str())
 .ok_or("Missing 'path' parameter".to_string())?;

 // 2. Safeguard: Prevent path traversal (Sandboxing)
 // In a production environment, chroot or a dedicated virtual directory should be used.
 if !file_path.ends_with(".log") {
 return Err("Only .log files are allowed".into());
 }

 // 3. File system access (wrapping synchronous I/O in an asynchronous context)
 let content = fs::read_to_string(file_path)
 .map_err(|e| format!("Failed to read file: {}", e))?;

 // 4. Result formatting
 Ok(serde_json::json!({
 "status": "success",
 "content": content,
 "lines": content.lines().count()
 }))
 }
}

3.4. Main Loop and JSON-RPC Server

This is the main loop responsible for communication with the LLM. It reads JSON-RPC requests from standard input and outputs the processing results to standard output.

use tokio::io::{AsyncBufReadExt, BufReader};
use tokio::io::{AsyncWriteExt, BufWriter};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
 let stdin = tokio::io::stdin();
 let stdout = tokio::io::stdout();
 let mut reader = BufReader::new(stdin).lines();
 let mut writer = BufWriter::new(stdout);

 let tool = Arc::new(LogReaderTool);

 // Process requests as they arrive from the LLM or host
 while let Ok(Some(line)) = reader.next_line().await {
 if line.trim().is_empty() { continue; }

 if let Ok(json_req) = serde_json::from_str::<Value>(&line) {
 let method = json_req.get("method").and_then(|m| m.as_str()).unwrap_or("");
 let id = json_req.get("id");

 if method == "tools/call" || method == "tools/invoke" {
 let params = json_req.get("params").cloned().unwrap_or(Value::Null);
 
 // Execute business logic
 let result = tool.handle(params).await;
 
 let response = match result {
 Ok(data) => serde_json::json!({
 "jsonrpc": "2.0",
 "id": id,
 "result": data
 }),
 Err(e) => serde_json::json!({
 "jsonrpc": "2.0",
 "id": id,
 "error": { "code": -32000, "message": e }
 })
 };
 
 writer.write_all(response.to_string().as_bytes()).await?;
 writer.write_all(b"\n").await?;
 writer.flush().await?;
 }
 }
 }
 Ok(())
}

4. Optimization and Deployment Considerations

The code above provides a basic framework, but for production environments like ZeroClaw, consider the following:

Concrete Error Types: Use specific thiserror or anyhow-based error types instead of String to facilitate debugging.
Security Sandboxing: Use a virtual file system (VFS) library instead of std::fs to prevent agents from accessing the entire system.
Graceful Shutdown: Utilize tokio’s signal module to handle interrupt signals (SIGTERM) and safely terminate ongoing file operations.

5. Conclusion

Rust is the ideal language for building reliable MCP servers due to its type safety and memory management capabilities. Based on the code above, by integrating with a blog-api-server or monitoring system, you can build a fully automated cycle where AI models directly analyze system logs and suggest patches.

In the next post, we will cover how to agentize this MCP server on the ZeroClaw runtime and communicate with other services.

Enhancing AI Agent Reliability: A Guide to Integrating Forge Guardrails with MCP

Wed, 20 May 2026 09:00:35 +0900

Recent advancements in AI agents powered by Large Language Models (LLMs) have been remarkable. A notable case on Hacker News, “Forge – Guardrails take an 8B model from 53% to 99% on agentic tasks,” highlighted how applying appropriate Guardrails can dramatically increase the success rate of specific tasks, often more effectively than simply increasing model parameter count.

For our ongoing projects, ZeroClaw and those based on MCP (Model Context Protocol), agent reliability is paramount. In this post, we will explore the concept of Forge, an open-source guardrail framework, and introduce practical methods for integrating it into our existing MCP architecture to ensure agent stability.

Problem Definition: The Dilemma of Autonomy

Granting agents more autonomy increases the risk of unexpected behavior. For instance, when an MCP request is made to generate a blog post, an agent might attempt to execute system commands or call unauthorized APIs.

Our previous implementation of [blog-api-server] attempted to mitigate this through prompt engineering and basic JSON schema validation, but these proved insufficient in complex multi-agent environments. To address this, we decided to introduce an L1 Guardrail layer for pre-filtering inputs and outputs.

Solution: Applying the Guardrails Pattern

As demonstrated by Forge, the key to improving agent task success rates (53% → 99%) lies in pre-execution validation. We designed a structure where a middleware layer validates the agent’s responses before they are delivered to the user or used to execute tools.

Architecture Overview

A Validator layer is placed between the existing MCP client and the LLM to perform the following:

Input Validation: Checks if user requests violate system policies (e.g., filtering for aggressive prompts).
Output Validation: Verifies if LLM-generated JSON or function call arguments conform to the schema.

Practical Code Example: Implementing Safeguards in Rust

Let’s implement a lightweight output validator within the Rust environment of ZeroClaw. This example uses serde and regex to safely wrap code execution commands generated by the LLM, without complex external libraries.

1. Implementing Validation Logic

First, here’s a simple validator to determine if a command generated by the agent is safe.

use regex::Regex;
use serde::{Deserialize, Serialize};

// Structure for commands an agent might generate
#[derive(Debug, Serialize, Deserialize)]
struct AgentCommand {
 tool_name: String,
 parameters: String,
}

pub struct Guardrail;

impl Guardrail {
 // Simple example for filtering dangerous strings
 fn is_dangerous(input: &str) -> bool {
 let dangerous_patterns = vec!["rm -rf", "sudo", "eval", "__import__"];
 dangerous_patterns.iter().any(|&pat| input.contains(pat))
 }

 // Validation logic before command execution
 pub fn validate_command(cmd: &AgentCommand) -> Result<&AgentCommand, String> {
 // 1. Check tool name against a whitelist
 let allowed_tools = vec!["blog_post", "search", "read_file"];
 if !allowed_tools.contains(&cmd.tool_name.as_str()) {
 return Err(format!("Attempt to use disallowed tool: {}", cmd.tool_name));
 }

 // 2. Check for dangerous keywords within parameters
 if Self::is_dangerous(&cmd.parameters) {
 return Err("Potentially dangerous command included in parameters.".to_string());
 }

 // 3. If safe, approve the command
 Ok(cmd)
 }
}

2. Integrating into the Agent Loop

Now, we connect the validator to the request processing loop of the MCP server. After the agent generates a response, it must pass through the Guardrail before the actual system executes it.

// Hypothetical agent execution function
fn execute_agent_task(llm_output: &str) -> Result<String, String> {
 // 1. Parse LLM output (in reality, this would involve JSON parsing, etc.)
 // We assume parsing is successful here for simplicity.
 let command = AgentCommand {
 tool_name: "blog_post".to_string(),
 parameters: "title: 'Hello World'".to_string(),
 };

 // 2. Before guardrail passage
 println!("[System] LLM response received: {}", command.tool_name);

 // 3. Execute guardrail validation
 let safe_command = Guardrail::validate_command(&command)?;

 // 4. Execute validated command
 println!("[System] Executing safe command...");
 // Actual tool execution logic (e.g., calling the blog API)
 Ok("Post successfully created.".to_string())
}

fn main() {
 // Normal case
 match execute_agent_task("valid_response") {
 Ok(msg) => println!("Success: {}", msg),
 Err(e) => println!("Blocked: {}", e),
 }

 // Simulate an abnormal case
 let malicious_cmd = AgentCommand {
 tool_name: "system_shell".to_string(), // Not in whitelist
 parameters: "rm -rf /".to_string(),
 };

 match Guardrail::validate_command(&malicious_cmd) {
 Ok(_) => println!("Error: Hacker has infiltrated!"),
 Err(e) => println!("Protected: {}", e), // "Protected: Attempt to use disallowed tool: system_shell"
 }
}

Benefits and Outlook

By establishing this L1 defense line, we gain the following advantages:

Improved Stability: Similar to the Forge case, even 8B models can be utilized safely, reducing inference costs.
Enhanced Transparency: Logs clearly indicate why an agent rejected a specific task.
Maintainability: Security policy changes only require modifications to the Guardrail module.

Moving forward, the ZeroClaw project plans to integrate this validation logic into an asynchronous runtime, enabling real-time safety monitoring during inter-agent communication ([Discord MCP], [Cloud Monitor]).

Instead of solely focusing on improving model performance, the key to deploying AI agents in actual production environments will lie in how we design system-level safeguards like these.

This article was written with reference to architectural design documents related to ZeroClaw and MCP.

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.

Maximizing Development Productivity by 17x: Building a Low-Cost AI Agent Loop with DeepSeek V4 and Claude Code

Mon, 04 May 2026 09:01:31 +0900

Maximizing Development Productivity by 17x: Building a Low-Cost AI Agent Loop with DeepSeek V4 and Claude Code

Recently, an interesting project called DeepClaude was introduced on Hacker News. It is a hybrid architecture that combines DeepSeek V4 Pro with Claude Code’s Agent Loop feature to deliver the same performance at a 17 times lower cost compared to existing solutions.

This article will not merely deliver interesting news but will specifically cover how to build a cost-effective AI coding assistant by integrating Claude Code with DeepSeek V4 in a real development environment. In particular, it provides a comprehensive guide, including how to control GitHub and the file system using MCP (Model Context Protocol).

1. Why DeepSeek V4 and Claude Code?

Claude Code provides a powerful ‘Agent Loop’ feature. This is an automated process where the AI writes code, executes it, fixes errors, and repeats until the goal is achieved. However, the cost burden of continuously using the high-quality Sonnet model is significant.

This is where DeepSeek V4 Pro comes in. DeepSeek V4 is one of the most notable models in the open-source community recently, showing excellent performance not only in complex reasoning capabilities but also in code generation. Above all, its cost-effectiveness is overwhelming.

Core Strategy of the DeepClaude Approach:

Planner: Use the existing Claude model for analyzing tasks and establishing a plan (one-time use).
Worker: Use DeepSeek V4 for the actual code writing and modification loop (Run Loop) (high volume use).

Through this structure, it is possible to reduce the total cost to 1/17th while maintaining the task completion rate.

2. Prerequisites: Configuring the MCP Server Environment

To implement this architecture, the AI must be able to read and write files in the local environment. To do this, we will apply the MCP Server concept covered in the previous post for setup.

2.1. Configuring the MCP Settings File (`mcp_config.json`)

Configure the settings so the AI agent can access the project folder. Create a local mcp_config.json file and write the following content.

{
 "mcpServers": {
 "filesystem": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Projects/DeepAgent"],
 "env": {
 "ALLOWED_DIRECTORIES": "/Users/yourname/Projects/DeepAgent"
 }
 },
 "github": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-github"]
 }
 }
}

filesystem: Specifies the path where the agent will generate and modify code.
github: (Optional) Token environment variables may be required to create GitHub issues or PRs.

3. Implementing the Integration of DeepSeek V4 and Claude Code

Now, let’s implement a Python script that performs tasks by switching between the two models by writing actual code. This script is the core logic of the ‘Hybrid Agent’.

3.1. Installing Dependencies

pip install openai anthropic

3.2. Implementing the Hybrid Agent Code (`hybrid_agent.py`)

This code uses a mix of the Anthropic API and the OpenAI-compatible API (DeepSeek).

import os
import json
from openai import OpenAI
from anthropic import Anthropic

# Configuration: Manage API keys via environment variables
DEEPSEEK_API_KEY = os.getenv("DEEPSEEK_API_KEY")
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")

def create_hybrid_agent(task_description: str, max_iterations: int = 5):
 """
 Hybrid agent function combining DeepSeek V4 (Worker) and Claude (Planner)
 """
 
 # 1. Initialize Model Clients
 # DeepSeek V4 is accessed via OpenAI SDK (example)
 worker_client = OpenAI(
 api_key=DEEPSEEK_API_KEY,
 base_url="https://api.deepseek.com/v1" # Verify actual endpoint needed
 )
 planner_client = Anthropic(api_key=ANTHROPIC_API_KEY)

 print(f"[System] Task start: {task_description}")
 
 # 2. Request initial plan from Claude (Planner)
 planning_prompt = f"""
 You are a software architect. Please establish a concrete step-by-step plan to perform the following task.
 Task: {task_description}
 
 Please respond only with a step list in JSON format.
 Example: {{"steps": ["Create file", "Implement logic", "Run test"]}}
 """
 
 try:
 message = planner_client.messages.create(
 model="claude-3-5-sonnet-20241022",
 max_tokens=1024,
 messages=[{"role": "user", "content": planning_prompt}]
 )
 plan_text = message.content[0].text
 print(f"[Planner] Plan established: {plan_text}")
 except Exception as e:
 print(f"[Error] Failed to establish plan: {e}")
 return

 # 3. Execute DeepSeek V4 (Worker) Loop
 current_context = f"Task Goal: {task_description}\nPlan: {plan_text}"
 
 for i in range(max_iterations):
 print(f"\n--- Loop {i+1}/{max_iterations} (Worker: DeepSeek V4) ---")
 
 try:
 response = worker_client.chat.completions.create(
 model="deepseek-chat", # DeepSeek V4 model name
 messages=[
 {"role": "system", "content": "You are a professional developer who writes and modifies code according to the plan."},
 {"role": "user", "content": current_context}
 ],
 temperature=0.3
 )
 
 worker_output = response.choices[0].message.content
 print(f"[Worker] Execution Result:\n{worker_output[:500]}...\n") # Summarize output
 
 # (In actual implementation, call MCP tools here to write files or execute commands)
 # file_system_tool.write_file(path="main.py", content=worker_output)
 
 # Check termination condition (e.g., "TASK_COMPLETE" keyword)
 if "Done" in worker_output or "TASK_COMPLETE" in worker_output:
 print("[System] Task completed successfully.")
 break
 
 # Update context for feedback loop
 current_context += f"\n\nPrevious Attempt Result:\n{worker_output}\n\nPlease continue or fix errors."
 
 except Exception as e:
 print(f"[Error] Error occurred during Worker execution: {e}")
 break

# Execution Example
if __name__ == "__main__":
 create_hybrid_agent(
 task_description="Create a Next.js API handler to generate a /hello endpoint, and include TypeScript type validation."
 )

3.3. Code Explanation

Planner (Claude): Uses the anthropic library to analyze user requirements and define the order of tasks. Since this process occurs only once, using a high-cost model has little impact on the total cost.
Worker (DeepSeek V4): Calls the DeepSeek API via the openai library. It loops max_iterations times to generate code and repeatedly modifies it based on virtual feedback (or actual execution results). This is the part that consumes the most tokens.

4. Troubleshooting and Tips

1. DeepSeek API Compatibility: DeepSeek V4 Pro is currently often provided in a way compatible with the OpenAI SDK, but you may need to configure the Base URL (e.g., https://api.deepseek.com). Please check the official documentation.

2. Context Window: DeepSeek models usually support a long context window of 128k or more. This is very advantageous for analyzing long codebases or maintaining conversation history. Even if the context lengthens as the loop runs, there is little performance degradation.

3. MCP Integration: The Python code above is a simple example. In reality, you must communicate with the server defined in mcp_config.json to access the file system. To do this, you need to implement client logic that communicates with the MCP server via stdio inside hybrid_agent.py to enable full automation.

5. Conclusion: Balancing Cost and Performance

For developers, AI is becoming not just a simple chat window but an ‘Acting Agent’. However, indiscriminately using GPT-4o or Claude Sonnet without regard for cost is not realistic.

The hybrid strategy of placing a high-performance open-source model like DeepSeek V4 as the ‘Worker’ and utilizing a high-cost model as the ‘Planner’ is likely to become the standard pattern for future AI agent development.

Test the code above right now and add 17x efficiency to your development workflow.

Getting Started with MCP Servers: Creating Your First Tool Integrated with Claude Code

Sun, 03 May 2026 10:47:00 +0900


# Getting Started with MCP Servers: Creating Your First Tool Integrated with Claude Code

MCP (Model Context Protocol) is a powerful protocol that can be integrated with Claude Code and other AI tools. This guide will walk you through the process of creating your first MCP server step-by-step.

## What is MCP?

MCP is a standard protocol that allows AI agents to access external tools and resources. Key features:

- **Standardized Interface**: Integrate various tools in a unified manner
- **Resource Sharing**: Safely access resources such as files and databases
- **Extensibility**: Easily add new tools

## Basic MCP Server Structure

```typescript
// mcp-server-template.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server(
 {
 name: 'my-mcp-server',
 version: '1.0.0'
 },
 {
 capabilities: {
 tools: {},
 resources: {}
 }
 }
);

// Example of tool registration
server.setRequestHandler(ListToolsRequestSchema, async () => ({
 tools: [
 {
 name: 'my_tool',
 description: 'Description of my tool',
 inputSchema: {
 type: 'object',
 properties: {
 param1: {
 type: 'string',
 description: 'Parameter description'
 }
 },
 required: ['param1']
 }
 }
 ]
}));

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

Practical Example: Simple Calculator MCP Server

// calculator-mcp-server.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';

const server = new Server(
 { name: 'calculator-server', version: '1.0.0' },
 { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
 tools: [
 {
 name: 'calculate',
 description: 'Perform basic mathematical operations',
 inputSchema: {
 type: 'object',
 properties: {
 expression: {
 type: 'string',
 description: 'Expression to calculate (e.g., "2 + 2")'
 }
 },
 required: ['expression']
 }
 }
 ]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
 if (request.params.name === 'calculate') {
 const expression = request.params.arguments?.expression as string;
 try {
 // Use Function instead of eval for safer calculation
 const result = Function(`"use strict"; return (${expression})`)();
 return {
 content: [{
 type: 'text',
 text: `Result: ${result}`
 }]
 };
 } catch (error) {
 return {
 content: [{
 type: 'text',
 text: `Calculation error: ${error}`
 }],
 isError: true
 };
 }
 }
 return { content: [] };
});

Claude Code Configuration

To register an MCP server with Claude Code, modify ~/.config/claude/settings.json:

{
 "mcpServers": {
 "calculator": {
 "command": "node",
 "args": ["/path/to/calculator-mcp-server.js"]
 }
 }
}

Providing Resources

// Provide resource list
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
 resources: [
 {
 uri: 'calc://history',
 name: 'Calculation History',
 description: 'Recent calculation history',
 mimeType: 'application/json'
 }
 ]
}));

// Provide resource content
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 if (request.params.uri === 'calc://history') {
 return {
 contents: [{
 uri: request.params.uri,
 mimeType: 'application/json',
 text: JSON.stringify({ history: [] })
 }]
 };
 }
 throw new Error('Resource not found');
});

Security Considerations

Input Validation: Validate and restrict all user input
Access Control: Apply the principle of least privilege
Error Handling: Ensure sensitive information is not exposed in error messages
Rate Limiting: Implement rate limiting to prevent excessive requests

Deployment and Testing

# Build server
npm run build

# Local test
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/server.js

# Test after integrating with Claude Code
# Use tool in Claude Code after reloading config file

Next Steps

Add more complex tools and resources
Implement prompt templates
Improve error handling
Add logging and monitoring

Developing MCP servers is a great way to extend Claude Code’s functionality and enhance automation. Start with small projects and gradually expand your features.

References

Building a Blog AI Auto-Comment System (1/3) — Architecture and Implementation

Sun, 03 May 2026 01:00:00 +0900

Overview

I built a system where AI automatically responds to blog comments. When a reader leaves a comment on a blog post, the AI assistant analyzes the post context and automatically generates a technically accurate yet friendly reply.

This series consists of three parts:

Part 1 (This post): Overall architecture design and core code implementation
Part 2: File-based authentication, permission management, security hardening
Part 3: systemd deployment, nginx proxy, troubleshooting

System Architecture

Overall Data Flow

Reader writes a comment
 ↓
[giscus] → Creates a comment on GitHub Discussions
 ↓
[GitHub Webhook] → Sends HTTP POST
 ↓
[nginx reverse proxy] → Header forwarding
 ↓
[Flask Worker] → Signature verification → Comment analysis
 ↓
[Claude Code CLI] → Generates AI response
 ↓
[GitHub GraphQL API] → Posts reply to Discussion
 ↓
[giscus] → Displays reply on blog

The key point in this architecture is that giscus uses GitHub Discussions as a comment storage. Therefore, we can receive new comment events via GitHub Webhook and post responses using the same GitHub API.

Components

Component	Role	Technology
giscus	Blog comment widget	Based on GitHub Discussions
GitHub Webhook	Event delivery	`discussion_comment` event
nginx	Reverse proxy	Header forwarding, SSL termination
Flask Worker	Webhook receiving and processing	Python, Flask, Flask-Limiter
Claude Code	AI response generation	`--print` mode CLI call
GitHub GraphQL	Response posting	Mutation API

giscus Configuration

To integrate giscus into a Hugo blog, the following configuration is required in hugo.toml:

[params]
 [params.comments]
 enabled = true
 provider = "giscus"
 [params.comments.giscus]
 repo = "yarang/blogs"
 repoId = "YOUR_REPO_ID"
 category = "General"
 categoryId = "YOUR_CATEGORY_ID"
 mapping = "pathname"
 strict = "0"
 reactionsEnabled = "1"
 emitMetadata = "0"
 inputPosition = "bottom"
 lang = "ko"
 theme = "noborder_gray"

mapping = "pathname" maps Discussions based on the post URL path. This creates an independent Discussion for each blog post.

GitHub Webhook Configuration

In the GitHub repository Settings > Webhooks:

Payload URL: https://your-domain/webhook
Content type: application/json
Secret: Secret for HMAC-SHA256 signature (covered in detail in the security post)
Events: Select Discussion comments

The Webhook sends a discussion_comment event to the Flask worker whenever a comment is created.

Flask Worker Implementation

Project Structure

auto-comment-worker/
├── scripts/
│ └── auto-comment-worker.py # Main worker
├── deploy/
│ └── auto-comment-worker.service # systemd service
├── venv/ # Python virtual environment
└── logs/
 └── audit.log # Audit log

Core Dependencies

from flask import Flask, request, jsonify
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address
from marshmallow import Schema, fields, validate, ValidationError

Flask: Provides Webhook endpoints as a lightweight web framework
Flask-Limiter: Prevents abuse with rate limiting (10 times per minute)
marshmallow: Safe data parsing via request schema validation

Webhook Endpoint

@app.route('/webhook', methods=['POST'])
@limiter.limit("10 per minute")
def github_webhook():
 """Receives GitHub Webhook"""
 # 1. Signature verification
 signature = request.headers.get('X-Hub-Signature-256')
 if not verify_webhook_signature(request.data, signature):
 log_audit('SIGNATURE_INVALID', {'ip': request.remote_addr})
 return jsonify({'status': 'unauthorized'}), 401

 # 2. Request schema validation
 schema = WebhookSchema()
 try:
 payload = schema.load(request.json)
 except ValidationError as err:
 return jsonify({'status': 'invalid'}), 400

 # 3. Extract and filter comment information
 comment = payload.get('comment', {})
 discussion = payload.get('discussion', {})
 original_author = comment.get('user', {}).get('login', 'User')

 # Ignore if it's the blog owner's comment
 if _is_blog_owner(original_author):
 return jsonify({'status': 'owner_comment_ignored'}), 200

 # Ignore if AI generated comment (prevent infinite loop)
 if _is_ai_generated_comment(comment.get('body', '')):
 return jsonify({'status': 'ai_comment_ignored'}), 200

 # 4. Generate and post AI response
 discussion_graphql_id = get_discussion_graphql_id(
 repo_owner, repo_name, discussion_number
 )
 context = f"Title: {discussion_title}\n\nContent: {discussion_body}"
 reply = analyze_comment(context, comment_body)
 post_reply_graphql(discussion_graphql_id, comment_body, original_author, reply)

The core flow consists of 4 steps:

Signature verification: Verifies if the request came from GitHub using HMAC-SHA256
Schema validation: Validates payload structure with marshmallow
Filtering: Ignores comments from the blog owner and the AI itself (prevents infinite loops)
Response: Generates AI response with Claude Code and posts via GraphQL API

Preventing Infinite Loops

If AI responds to a comment created by AI, it will fall into an infinite loop. To prevent this, we use marker-based detection:

def _is_ai_generated_comment(body: str) -> bool:
 """Identifies if the comment was generated by AI"""
 ai_markers = [
 '🤖 AI Assistant',
 'AI Assistant',
 'AgentForge',
 'Automatically generated by Claude Code',
 'was automatically generated'
 ]
 body_lower = body.lower()
 return any(marker.lower() in body_lower for marker in ai_markers)

When posting the AI response, you must include one of these markers in the body:

body = f"""---
**🤖 AI Assistant**

{safe_reply}

*This comment was automatically generated by AgentForge + Claude Code.*
---
"""

Calling Claude Code CLI

Use Claude Code’s --print mode to generate an AI response non-interactively:

def analyze_comment(context: str, comment: str) -> str:
 """Run Claude Code with AgentForge settings"""
 prompt = f"""## Blog Post Context
{context[:2000]}

## Reader Comment
{comment}

Please write a response to this comment.
- As a technical blog assistant, be professional yet friendly
- Concise within 200 characters
- Provide additional info or links if needed
"""

 cmd = [
 CLAUDE_CODE_PATH,
 '--settings', AGENTFORGE_CONFIG,
 '--print', prompt
 ]

 result = run(cmd, capture_output=True, text=True, timeout=60)

 if result.returncode == 0 and result.stdout.strip():
 return result.stdout.strip()

 return "Thanks for your opinion! I think it would be great to discuss the technical aspects further. 🙏"

Specify the AgentForge dedicated configuration file with the --settings flag. You can manage the model, token limits, etc. in this configuration file.

The --print flag runs Claude Code in non-interactive mode and outputs the result to stdout. Unlike interactive mode, it terminates after a single prompt-response.

GitHub GraphQL API Integration

Since giscus uses GitHub Discussions, the response must also be posted via the GitHub GraphQL API.

Retrieve Discussion GraphQL ID:

def get_discussion_graphql_id(repo_owner, repo_name, discussion_number):
 query = """
 query($owner: String!, $name: String!, $number: Int!) {
 repository(owner: $owner, name: $name) {
 discussion(number: $number) {
 id
 }
 }
 }
 """
 variables = {
 "owner": repo_owner,
 "name": repo_name,
 "number": discussion_number
 }

 response = requests.post(
 GITHUB_API_URL,
 json={"query": query, "variables": variables},
 headers={
 "Authorization": f"Bearer {GITHUB_TOKEN}",
 "Content-Type": "application/json"
 },
 timeout=10
 )

 if response.status_code == 200:
 data = response.json()
 return data["data"]["repository"]["discussion"]["id"]
 return None

The Webhook payload only includes the Discussion’s REST API ID. However, to post a comment, the GraphQL Node ID is required. Therefore, we first retrieve the Discussion’s Node ID via a GraphQL query, then use it to post the comment.

Post Response (Mutation):

def post_reply_graphql(discussion_graphql_id, original_comment, original_author, reply):
 query = """
 mutation($discussionId: ID!, $body: String!) {
 addDiscussionComment(input: {
 discussionId: $discussionId, body: $body
 }) {
 comment { id, databaseId }
 }
 }
 """
 # ... (Send request)

The addDiscussionComment mutation adds a new comment to the entire Discussion. It is a Discussion-level comment, not a reply to a specific comment.

Input Sanitization

Since user comments are external input, they must be sanitized:

def sanitize_comment(body: str) -> str:
 """User input sanitization"""
 if not body:
 return body
 body = re.sub(r'<[^>]+>', '', body) # Remove HTML tags
 body = html.escape(body) # Escape HTML entities
 body = body[:1000] # Length limit
 return body

To prevent XSS attacks, HTML tags are removed, remaining special characters are escaped, and the length is limited to 1000 characters.

Audit Logging

We keep audit logs to track security events:

def log_audit(event_type: str, details: dict):
 """Record security event audit log"""
 with open(AUDIT_LOG, 'a') as f:
 f.write(json.dumps({
 'timestamp': datetime.utcnow().isoformat(),
 'event': event_type,
 'details': details
 }) + '\n')

Event types recorded:

SIGNATURE_INVALID: Webhook signature verification failed
INVALID_PAYLOAD: Invalid request payload
WEBHOOK_RECEIVED: Webhook received successfully
AI_RESPONSE_SENT: AI response posted successfully

Conclusion

In this Part 1, we covered the overall architecture and core implementation code connecting giscus, GitHub Webhook, Flask worker, Claude Code CLI, and GitHub GraphQL API.

In the upcoming Part 2, we will cover security hardening for this system — file-based authentication management, file permission verification, HMAC-SHA256 signature verification, and more in detail.

This post is Part 1 of the AgentForge blog automatic comment system series.

Multi-Model AI Agent Team Design: Composed Architecture and 5-Team Hierarchy

Mon, 30 Mar 2026 00:33:34 +0900

Overview

For building a blog system, I designed a multi-model agent team consisting of 14 AI specialists, 5 teams, and 4 LLM models. The core innovations are two:

Composed Agent: Separating role definitions from execution profiles for maximum reusability
Hierarchical Bridge Leadership: Dual membership of tech leads between upper and lower teams to resolve communication bottlenecks

This post covers the final structure, model distribution strategy, and the composed architecture design process.

Background: Why Multi-Model?

Using a single LLM for all tasks creates two problems:

Cost: Running 14 specialists on a Claude Opus-level model makes costs uncontrollable
Fit: Design needs fast reasoning, security analysis needs deep logic, implementation needs stable coding

So we distributed models based on task characteristics.

Final Team Structure

5 teams, 14 specialists, 4 models.

graph TD
 subgraph UPPER["Upper — Steering Team · consensus"]
 ORC["Orchestrator
relay:steering-orchestrator"]
 DES["Architect
gemini:gemini-2.5-flash"]
 SEC["Security Reviewer
codex:gpt-4o"]
 STL["Backend Tech Lead
relay:developer-zai"]
 FTL["Frontend Tech Lead
relay:developer-zai"]
 DTL["Desktop Tech Lead
relay:developer-zai"]
 INF["Infra Network
gemini:gemini-2.5-flash"]
 SAD["Server Admin
relay:developer-zai"]
 end

 subgraph LOWER_BE["Backend Team · leader_decides"]
 BTL["Backend Tech Lead"]
 BDEV["Backend Developer"]
 end

 subgraph LOWER_FE["Frontend Team · leader_decides"]
 FTL2["Frontend Tech Lead"]
 FDEV["Frontend Developer"]
 FUX["UX Designer"]
 end

 subgraph LOWER_DT["Desktop Team · leader_decides"]
 DTL2["Desktop Tech Lead"]
 DDEV["Desktop Developer"]
 DUX["UX Designer"]
 end

 subgraph LOWER_INFRA["Infra Team · leader_decides"]
 SAD2["Server Admin (Leader)"]
 INET["Cloud Network"]
 DBA["DB Architect"]
 end

 UPPER -.->|bridge| LOWER_BE
 UPPER -.->|bridge| LOWER_FE
 UPPER -.->|bridge| LOWER_DT
 UPPER -.->|bridge| LOWER_INFRA

 BTL --> BDEV
 FTL2 --> FDEV
 FTL2 --> FUX
 DTL2 --> DDEV
 DTL2 --> DUX
 SAD2 --> INET
 SAD2 --> DBA

Team Details

Team	Type	Decision-Making	Leader	Members
Steering Team	upper	consensus	Orchestrator	8 (including bridges)
Backend Team	lower	leader_decides	Backend Tech Lead	2
Frontend Team	lower	leader_decides	Frontend Tech Lead	3
Desktop Team	lower	leader_decides	Desktop Tech Lead	3
Infra Team	lower	leader_decides	Server Admin	3

The Infra Team Separation Decision

In the initial design, DB Architect and Server Admin were part of the backend team. But we separated them based on workspace.

graph LR
 subgraph BackendTeam["Backend Team"]
 B["API Code Writing
FastAPI, Python
workspace: VS Code / SSH"]
 end

 subgraph InfraTeam["Infra Team"]
 S["Server Management
Docker, Ubuntu, Nginx
workspace: SSH Terminal"]
 N["Cloud Network
Cloudflare Dashboard
workspace: Web Console"]
 D["DB Management
PostgreSQL, Migrations
workspace: psql / SSH"]
 end

 B -.->|API deployment| S
 B -.->|Query optimization| D

When workspaces differ, separation is more natural than keeping them together.

Model Distribution Strategy

pie title Specialists by Model
 "relay:developer-zai (GLM)" : 10
 "gemini:gemini-2.5-flash" : 2
 "codex:gpt-4o" : 1
 "zai:glm-4" : 1

Model	Specialists	Purpose	Why Chosen
relay:developer-zai	10	Implementation, ops, leads	Cost-effective, stable coding
gemini:gemini-2.5-flash	2	Design, infra network	Fast response, easy external API calls
codex:gpt-4o	1	Security review	High reasoning, OWASP knowledge
zai:glm-4	1	Context compression	Free tier, text summarization specialized

By assigning 10 implementation specialists to GLM, we achieved 60-70% total cost reduction.

Composed Agent Architecture

The core innovation is separating role definitions (Expert) from execution profiles (Definition).

With the traditional approach, role and execution logic are coupled — any change requires a full rewrite, and reuse is impossible.

Composed Approach

graph TD
 DEF["Definition
Backend Developer"]
 DEF --> BASE["Base: backend-core"]
 DEF --> CAP["Capabilities:
rest-api, crud, auth-jwt"]
 DEF --> PLAT["Platform: fastapi"]
 DEF --> POL["Policy: blog-default"]

 BASE --> |"compose"| RUN["Runtime Agent"]
 CAP --> |"compose"| RUN
 PLAT --> |"compose"| RUN
 POL --> |"compose"| RUN

Module Structure

agent-library/
├── definitions/ ← 14 agent definitions
├── modules/
│ ├── base/ ← 6 base modules
│ ├── capabilities/ ← 15 capability modules
│ ├── platforms/ ← 5 platform modules
│ └── policies/ ← 1 policy
└── runs/ ← execution history

Advantages

Reusability: rest-api capability module shared by backend developer and backend tech lead
Platform swap: Change platform: fastapi to platform: django for instant switching
Capability extension: Add a new capability module and connect it to the Definition
Policy unification: All agents follow the same blog-default policy

Expert-Definition Mapping

Expert	Definition	Base	Capabilities	Platform
Backend Developer	backend-developer	backend-core	rest-api, crud, auth-jwt	fastapi
Backend Tech Lead	backend-tech-lead	backend-core	rest-api, crud, code-review	fastapi
Frontend Developer	frontend-developer	frontend-core	markdown-renderer, list-filter-sort	nextjs
Server Admin	server-administrator	server-core	docker-management, nginx-config, postgres-admin	ubuntu
Infra Network	infra-network-admin	infra-core	dns-management, ssl-certificates, rate-limiting	cloudflare
Security Reviewer	security-auditor	specialist-core	security-audit	fastapi
Context Compressor	context-compressor	specialist-core	context-compression	markdown

TLS Certificate Strategy: Cloudflare Origin CA

For production TLS certificates, we chose Cloudflare Origin CA over Let’s Encrypt.

sequenceDiagram
 participant Client as Visitor
 participant CF as Cloudflare (Proxy)
 participant Nginx as Nginx (Origin)
 participant API as FastAPI

 Client->>CF: HTTPS request
 CF->>CF: Terminate with Cloudflare-managed cert
 CF->>Nginx: Encrypt with Origin CA cert
 Nginx->>API: HTTP (local)
 API-->>Nginx: Response
 Nginx-->>CF: Encrypted with Origin CA
 CF-->>Client: Response

Item	Let’s Encrypt	Cloudflare Origin CA
Validity	90 days (renewal required)	15 years (no renewal)
Issuance	ACME automation required	Manual from Dashboard
Complexity	certbot setup	Copy cert files only

Production architecture:

Oracle Cloud ARM (4 OCPU, 24GB)
├── PostgreSQL (installed directly on host)
├── Docker Compose
│ ├── blog-api (FastAPI)
│ ├── blog-frontend (Next.js standalone)
│ ├── MinIO (S3-compatible storage)
│ └── Nginx (Cloudflare Origin CA)
└── Cloudflare Proxy (Full Strict SSL)

Relay Plugin: Agent Invocation Mechanism

The team structure runs in Claude Code through the Relay plugin.

sequenceDiagram
 participant User as User
 participant Claude as Claude Code
 participant Plugin as Relay Plugin
 participant MCP as MCP Server
 participant LLM as External LLM

 User->>Claude: /relay:invoke-agent
 Claude->>Plugin: Load definition by expert slug
 Plugin->>Plugin: Compose Definition (base + capabilities + platform + policy)
 Plugin->>Plugin: Check backed_by

 alt relay:developer-zai
 Plugin->>Claude: Run internal agent
 else gemini:*
 Plugin->>MCP: Call gemini_mcp server
 MCP->>LLM: Gemini API
 LLM-->>MCP: Response
 MCP-->>Plugin: Result
 else codex:*
 Plugin->>MCP: Call codex_mcp server
 MCP->>LLM: OpenAI API
 LLM-->>MCP: Response
 MCP-->>Plugin: Result
 end

 Plugin-->>Claude: Final result
 Claude-->>User: Response

backed_by Namespaces

Namespace	MCP Server	Purpose
`relay:developer-zai`	internal agent	Implementation, ops (low cost)
`relay:steering-orchestrator`	internal agent	Coordination, final decisions
`gemini:gemini-2.5-flash`	gemini_mcp	Design, external APIs
`codex:gpt-4o`	codex_mcp	Security analysis
`zai:glm-4`	zai_mcp	Context compression

Design Decision Log

Decision	Alternative	Rationale
Separate infra team	Include in backend	Different workspaces (SSH vs IDE)
Cloudflare Origin CA	Let’s Encrypt	15-year validity, no renewal
PostgreSQL on host	Docker container	Memory efficiency on single server
Composed agent	Single-definition agent	Module reusability, easy platform swap
Assign many GLM	Assign many Claude	60-70% cost reduction

Retrospective: What I Learned

1. “Executable Structure” over “Perfect Structure”

Trying to design everything perfectly can prevent you from ever starting. It’s better to compromise and improve as you execute.

2. Workspace Defines Team Boundaries

People who write code and people who manage servers have different physical work environments — that’s a natural team boundary.

3. The Value of Composed Architecture

In an environment with 14 specialists, 5 teams, and 4 models interacting, module separation is essential. It minimizes the scope of changes and maximizes reusability.

4. Cost is Determined at Design Time

Asking “does this task really need a high-cost model?” every time naturally optimizes costs.

Next Steps

Start Phase 1 implementation: DB, Auth, Post/Category CRUD, Docker
Share team operation experience: Problems encountered during actual execution
Performance monitoring: Response time per model, cost vs quality analysis

This post summarizes my experience building an AI agent team using Claude Code + Relay plugin. It reflects learnings from applying this to a real project — different approaches may be more suitable depending on your situation.

Boosting Server Management Efficiency: Introducing Server Status Checker Skill

Mon, 09 Mar 2026 00:30:00 +0900

Boosting Server Management Efficiency: Introducing Server Status Checker Skill

Are you managing an increasing number of servers?

Individually connecting via SSH to check the status of each server is a waste of time. If you could grasp the CPU, memory, and disk usage of all servers at a glance, your work efficiency would improve significantly.

I faced this problem too, so I built a solution.

The Problem: Repetitive Server Monitoring Tasks

If you’re a DevOps engineer or system administrator, you’ve likely faced this situation:

Repeated SSH connections to each server
Manually running commands like top, htop, df
Manually recording status in Excel or Notion
Modifying management scripts as servers increase

This process wastes time and is repetitive work that can lead to mistakes.

The Solution: Server Status Checker Skill

Server Status Checker is a skill for Claude Code that checks the status of all servers in parallel based on your SSH config file.

Key Features

Feature	Description
Automatic SSH Config Parsing	Automatically discovers server list from `~/.ssh/config`
Real-time Status Check	Collects CPU, Memory, Disk, Uptime, Load information
Parallel Connections	Fast status checking with asyncssh (in seconds)
Group Classification	Automatically categorizes by GCP, OCI, GitHub, Blog, Local, etc.
Online/Offline Status	Intuitive status display with ✓ / ✗

Usage

# Check all server status
/server-status-checker

# Check specific server only
/server-status-checker --server mini01

# Output in JSON format
/server-status-checker --json

# Verbose error messages
/server-status-checker --verbose

Output Example

=== Server Status Report ===

[GCP Servers]
✗ gcp-ajou-ec1 - Offline (Authentication failed)
✗ gcp-fcoinfup-ec1 - Offline (Authentication failed)

[OCI Ajou]
✓ oci-ajou-ec1 - Online
 CPU: 15.2% | Memory: 62.3% | Disk: 45.8%
 Uptime: 15 days | Load: 1.23 1.45 1.38
 OS: Ubuntu 22.04 LTS

[Local Servers]
✓ mini01 - Online
 CPU: 6.7% | Memory: 45.2% | Disk: 5.0%
 Uptime: 2 days | Load: 2.17 2.11 1.94
 OS: macOS 26.3.1

Technical Details

SSH Config Parsing

Parses ~/.ssh/config file to automatically extract:

Host (hostname)
HostName (IP address or domain)
User (username)
Port (port number)
IdentityFile (SSH key path)

Asynchronous Parallel Processing

Uses Python’s asyncssh library to connect to all servers simultaneously:

async def check_server(host: str):
 # SSH connection and command execution
 result = await asyncssh.connect(...)
 return status

Checking 30 servers sequentially takes 5 minutes, but parallel processing completes in under 30 seconds.

Automatic Group Classification

Automatically classifies based on server name patterns:

Group	Pattern	Examples
GCP	`gcp-` prefix	gcp-ajou-ec1, gcp-fcoinfup-ec1
OCI Ajou	`oci-ajou-` prefix	oci-ajou-ec1
OCI Fcoinfup	`oci-fcoinfup-` prefix	oci-fcoinfup-ec1
GitHub	`github-as-` prefix	github-as-actions
Blog	`blog`	blog
Local	`mini`, `mac`	mini01, macbook-pro

System Metrics Collection

Collects the following information from each server:

Linux:

CPU: /proc/stat or psutil.cpu_percent()
Memory: /proc/meminfo or psutil.virtual_memory()
Disk: psutil.disk_usage()
Uptime: /proc/uptime or psutil.boot_time()
Load: /proc/loadavg or os.getloadavg()

macOS:

CPU: psutil.cpu_percent()
Memory: psutil.virtual_memory()
Disk: psutil.disk_usage()
Uptime: psutil.boot_time()
Load: os.getloadavg()

GitHub Release

This skill is released as open source.

🔗 GitHub: https://github.com/yarang/skill-server-status-checker

Installation

git clone https://github.com/yarang/skill-server-status-checker.git
cp -r skill-server-status-checker ~/.claude/skills/server-status-checker

Business Value

Aspect	Improvement
Time Savings	90% reduction in server check time (5 min → 30 sec)
Real-time Monitoring	Immediate server status awareness
Centralized Management	Manage all servers with single SSH config file
Automation	Minimize human errors by eliminating repetitive tasks

Use Cases

1. Daily Server Health Check

Every morning, check all server status with a single /server-status-checker command.

2. Incident Response

When an incident occurs, immediately identify offline servers and take action.

3. Capacity Planning

Monitor disk usage trends to plan capacity expansion in advance.

4. Performance Monitoring

Track CPU and memory usage to identify bottlenecks.

Conclusion

Server Status Checker is more than a simple server status checking tool. It’s a productivity tool that helps DevOps engineers and system administrators focus on core tasks by eliminating repetitive work.

By leveraging the standardized SSH config file and providing fast results through parallel processing, you no longer need to connect to each server individually. Check the health status of all servers with a single command.

Through AI and automation, let’s improve system management efficiency and focus on more important problems.

Related Projects:

domain-checker - Domain availability checker tool

Tags: #DevOps #ServerMonitoring #OpenSource #Claude #AI #Productivity #SSH

Korean Version: 한국어 버전

Boosting Developer Productivity: Introducing Domain Checker Skill

Mon, 09 Mar 2026 00:20:00 +0900

Boosting Developer Productivity: Introducing Domain Checker Skill

What’s the first thing you consider when starting a new project? The “domain name,” of course.

What if your most desired name is already taken in .com or .ai? Have you visited whois sites one by one each time?

I did too. So I built a solution.

The Problem: Repetitive Domain Search Tasks

If you’re a startup founder or developer, you’ve likely faced this situation:

Desired domain is already registered
Visit 10 different whois sites
Manually create comparison table in Excel
Brainstorm alternative domain names

This process wastes time and drains creativity through repetitive work.

The Solution: Domain Checker Skill

Domain Checker is a skill for Claude Code that checks domain availability in real-time and compares costs.

Key Features

Feature	Description
Fast Parallel Lookup	Check 8 major TLDs simultaneously
3-Stage Fallback	RDAP → whois → DNS (ensures reliability)
Automatic Alternative Suggestion	Auto-discovers alternatives when all desired domains are taken
Cost Comparison Table	Shows annual cost and minimum contract period by TLD
Markdown Report	Automatically generates detailed result reports

Usage

# Basic lookup
/domain-checker myapp

# Result example
🔍 Domain Search: myapp*
 🔴 myapp.com (~$13/year)
 🔴 myapp.ai (~$75/year)
 🟢 myapp.io (~$38/year) ← Available!

Target TLDs

TLD	Annual Cost	Min Contract	Characteristics
.com	~$13	1 year	General, highest recognition
.ai	~$75	2 years	AI project specialized
.io	~$38	1 year	Tech startup preferred
.net	~$14	1 year	.com alternative
.co	~$28	1 year	Startup popular
.dev	~$13	1 year	Developer targeted
.tech	~$12	1 year	Tech-related, low cost
.app	~$14	1 year	App service specialized

Technical Details

3-Stage Fallback Mechanism

1. RDAP API → Most accurate, fast
2. whois CLI → Fallback when RDAP fails
3. DNS NS lookup → Last resort

Alternative Domain Suggestion

When all major domains are registered, automatically discovers alternatives:

Search Patterns:

Prefixes: get, try, use, go, my, the
Suffixes: hq, app, hub, lab, pro

Example: myapp → getmyapp.ai, myapp-hq.io, trymyapp.com

Asynchronous Parallel Processing

Uses Python async programming to check 8 TLDs simultaneously, delivering results within 2 seconds.

Real Usage Example

/domain-checker ai

Result:

# 🌐 Domain Search Report: `ai`

## Summary
| Item | Result |
|------|--------|
| Search Domain | `ai` |
| TLDs Checked | 8 |
| 🟢 Available | **0** |
| 🔴 Already Registered | 8 |

## 💡 Alternative Domain Name Suggestions
Domains available among variations of `ai`.

| Domain | Annual Cost | Notes |
|--------|-------------|-------|
| `ai-hq.ai` | ~$75/year | AI specialized (min 2-year contract) |
| `ai-hq.io` | ~$38/year | Tech startup preferred |

GitHub Release

This skill is released as open source.

🔗 GitHub: https://github.com/yarang/skill-domain-checker

Installation

git clone https://github.com/yarang/skill-domain-checker.git
cp -r skill-domain-checker ~/.claude/skills/domain-checker

Business Value

Aspect	Improvement
Time Savings	90% reduction in domain search time (10 min → under 1 min)
Cost Efficiency	Supports optimal selection through TLD comparison
Documentation	Easy team sharing with auto-generated reports
Productivity	Focus on core problems by automating repetitive tasks

Conclusion

Domain Checker is more than a simple domain search tool. It’s a productivity tool that helps developers and entrepreneurs escape repetitive tasks and focus on truly important problems.

By solving small daily inconveniences with AI and automation, we can create greater value.

Related Projects:

server-status-checker - SSH config-based server status checker

Tags: #DevTools #OpenSource #Claude #AI #Productivity #Domain

Korean Version: 한국어 버전

[ZeroClaw] Intro - High-Performance Rust Agent Runtime

Fri, 27 Feb 2026 19:30:00 +0900

Introducing ZeroClaw: High-Performance Rust Agent Runtime

ZeroClaw is a high-performance autonomous agent runtime built in Rust, designed for developers who need speed, efficiency, and reliability in their AI-powered applications.

Key Features

Performance First

Rust-native: Zero allocations where possible
Async/await with Tokio: Efficient concurrent operations
Streaming support: Real-time response streaming

Extensibility

Trait + Factory Architecture: Extend by implementing traits
25+ Built-in Tools: Shell, file ops, memory, browser, HTTP
Plugin-friendly: Add providers, channels, tools without core changes

Security by Default

Sandbox Support: Firejail, Bubblewrap, Landlock, Docker
Pairing Protocol: 6-digit CSPRNG code
Secret Storage: ChaCha20-Poly1305 AEAD encryption

Multi-Platform

20+ Messaging Channels: Telegram, Discord, Slack, WhatsApp, Signal, Matrix
13+ LLM Providers: OpenAI, Anthropic, Gemini, Ollama, Bedrock, OpenRouter

Quick Start

cargo install zeroclaw
zeroclaw config init
zeroclaw run --channel telegram

Architecture

ZeroClaw Agent
├── Providers (OpenAI, Anthropic, Gemini, Ollama)
├── Channels (Telegram, Discord, Slack, WhatsApp)
├── Tools (Shell, File, Memory, Browser, HTTP)
├── Memory (SQLite, PostgreSQL, Markdown)
└── Security (Policy, Sandbox, Secret Store)

Roadmap

Phase 1: Enhanced Multi-Agent (In Progress)
Phase 2: More Integrations
Phase 3: Enterprise Features

Korean Version: 한국어 버전

[LLM] How to Write Effective Prompts

Sat, 21 Feb 2026 20:40:00 +0900

Introduction

Writing effective prompts is essential for getting the most out of LLMs (Large Language Models). This article summarizes key principles and practical patterns of prompt engineering.

Core Principles of Good Prompts

1. Clarity

Avoid ambiguous expressions and be specific.

Bad Example:

Write good code

Good Example:

Implement a binary search tree in Python.
Include insert, search, and delete methods,
with time complexity of O(log n).

2. Provide Context

Give background information needed for the LLM to understand the task.

I'm a React beginner.
Explain the difference between useState and useEffect
with example code.

3. Role Playing

Set up responses from a specific expert’s perspective.

You are a senior backend developer with 10 years of experience.
Explain the pros and cons of microservices architecture.

4. Specify Output Format

Explicitly state the desired response format.

Summarize the following in a markdown table:
- Language features
- Pros and cons
- Use cases

Prompt Patterns

Chain of Thought

Guide step-by-step thinking for complex problems.

Let's think through this problem step by step:
1. First analyze the problem
2. Consider solutions
3. Write the final answer

Few-Shot Learning

Provide examples to teach the desired format.

Summarize in the following format:

Input: "The weather is nice today"
Output: Positive, Weather

Input: "The meeting was too long"
Output: Negative, Work

Input: "Started a new project"
Output: ?

Structured Prompts

Divide complex tasks into sections.

## Goal
Design a user authentication API

## Requirements
- Use JWT tokens
- Refresh token rotation
- Apply rate limiting

## Output
1. API endpoint specification
2. Sequence diagram
3. Security considerations

Common Mistakes

Mistake	Problem	Solution
Too long prompts	Key points get lost	Keep it concise
Ambiguous instructions	Unexpected results	Provide specific examples
Missing context	Inaccurate answers	Add background info
Unspecified format	Poor readability	Specify output format

Practical Checklist

Check before writing your prompt:

Is the goal clear?
Included necessary context?
Specified output format?
Stated constraints?
Would examples help?

Conclusion

Good prompts are clear, specific, and provide necessary context. Practice to improve your prompt writing skills.

References

Korean Version: 한국어 버전

Ai on Yarang's Tech Lair

RubyLLM: A Guide to an Integrated AI Interface for Rails

RubyLLM: A Guide to an Integrated AI Interface for Rails

What is RubyLLM?

Project Setup

Basic Usage: Chat Interface

1. Calling OpenAI GPT-4o

2. Easy Model Switching (Preventing Vendor Lock-in)

Practical Application: Implementing Streaming Responses

Conclusion: AI Development Trends in the Ruby Ecosystem

Resources

Building an MCP Server with Rust: Utilizing the ZeroClaw Architecture

Building an MCP Server with Rust: Utilizing the ZeroClaw Architecture

1. Core Requirements of an MCP Server

2. Architecture Design: ZeroClaw Style

3. Practical Code Examples

3.1. Dependency Setup (Cargo.toml)

3.2. Handler Trait Definition

3.3. Implementing the Log Reading Tool

3.4. Main Loop and JSON-RPC Server

4. Optimization and Deployment Considerations

5. Conclusion

Enhancing AI Agent Reliability: A Guide to Integrating Forge Guardrails with MCP

Problem Definition: The Dilemma of Autonomy

Solution: Applying the Guardrails Pattern

Architecture Overview

Practical Code Example: Implementing Safeguards in Rust

1. Implementing Validation Logic

2. Integrating into the Agent Loop

Benefits and Outlook

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

Maximizing Development Productivity by 17x: Building a Low-Cost AI Agent Loop with DeepSeek V4 and Claude Code

Maximizing Development Productivity by 17x: Building a Low-Cost AI Agent Loop with DeepSeek V4 and Claude Code

1. Why DeepSeek V4 and Claude Code?

2. Prerequisites: Configuring the MCP Server Environment

2.1. Configuring the MCP Settings File (mcp_config.json)

3. Implementing the Integration of DeepSeek V4 and Claude Code

3.1. Installing Dependencies

3.2. Implementing the Hybrid Agent Code (hybrid_agent.py)

3.3. Code Explanation

4. Troubleshooting and Tips

5. Conclusion: Balancing Cost and Performance

Getting Started with MCP Servers: Creating Your First Tool Integrated with Claude Code

Practical Example: Simple Calculator MCP Server

Claude Code Configuration

Providing Resources

Security Considerations

Deployment and Testing

Next Steps

References

Building a Blog AI Auto-Comment System (1/3) — Architecture and Implementation

Overview

System Architecture

Overall Data Flow

Components

giscus Configuration

GitHub Webhook Configuration

Flask Worker Implementation

Project Structure

Core Dependencies

Webhook Endpoint

Preventing Infinite Loops

Calling Claude Code CLI

GitHub GraphQL API Integration

Input Sanitization

Audit Logging

Conclusion

Multi-Model AI Agent Team Design: Composed Architecture and 5-Team Hierarchy

3.1. Dependency Setup (`Cargo.toml`)

2.1. Configuring the MCP Settings File (`mcp_config.json`)

3.2. Implementing the Hybrid Agent Code (`hybrid_agent.py`)