Technical Architecture on TorchTree

Pi Coding Agent in Practice: A Complete Guide from Installation to Everyday Use

Sat, 13 Jun 2026 02:01:27 +0800

Pi is an open-source terminal coding agent built by Mario Zechner, the author of libGDX. Its core is just 418 lines of TypeScript, providing four tools by default — read, write, edit, and bash — with all advanced features supplied through extensions and packages. Previously I analyzed Pi’s design philosophy at the architecture level. This article focuses on real-world use: how to install it, configure it, pick extension packages, and weave Pi into your daily development workflow.

Positioning: Pi’s role in the toolchain

Pi isn’t meant to replace every coding tool. Taking DeepakNess’s actual usage as an example, three tools each have their own division of labor:

OpenAI Codex: handles complex tasks on the main project
Cursor: everyday coding on the main project
Pi: side projects, experimental tasks, and one-off scripts, usually paired with cheaper open-source models

The core logic behind this layered strategy: use strong models plus heavyweight tools for high-complexity tasks, and lightweight agents plus low-cost models for simple or exploratory tasks — keeping overall spending in check.

Installation and first-time configuration

Installing Pi only takes a single command:

Once installed, launch it by typing pi in the terminal and authenticate with the /login command. Pi supports two authentication methods:

Subscription login: supports Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, Google Gemini CLI, and more
API key: choose “Use an API key” and enter your provider’s secret (e.g., DeepSeek)

Use /model or Ctrl+L to open the model selector. The author defaults to deepseek-v4-pro with the xhigh thinking level for deep analysis, switching to deepseek-v4-flash for quick tasks.

Three core extension packages

Pi installs extension packages with pi install. The following three cover most practical scenarios:

pi-web-access

Gives Pi web search, content scraping, YouTube transcription, and GitHub repository exploration capabilities.

The configuration file lives at ~/.pi/web-search.json:

pi-codex-goal

Adds a goal-tracking mechanism for long-running tasks, well-suited to complex tasks that require multiple steps.

pi-vision-proxy

When the main model lacks vision capabilities, it proxies image-analysis requests to a vision-capable model (such as Kimi K2.6).

The configuration-file system

Pi’s configuration is divided into two layers:

AGENTS.md (project context): placed in the project root or ~/.pi/agent/AGENTS.md, its contents are injected into the system prompt. Good for defining a project’s tech stack, coding conventions, and so on.

APPEND_SYSTEM.md (global behavior rules): located at ~/.pi/agent/APPEND_SYSTEM.md, appended to the end of the system prompt and given higher priority than AGENTS.md. Good for defining cross-project behavioral conventions, such as:

Automatically use the vision proxy when the main model lacks vision
Prefer local files, and only search the web when necessary
Explain high-risk edits and commands
Write concisely and avoid AI-sounding language

Shortcuts and common commands

Pi’s interaction design focuses on terminal efficiency:

Action	Shortcut / command	Notes
Open the model selector	Ctrl+L or /model	Quickly switch models
Cycle through models	Ctrl+P	Rotate through configured models
Adjust thinking level	Shift+Tab	Toggle thinking depth
Interrupt the current action	Escape	Cancel the running task
Send a steering message	Enter	Interrupt the agent’s current workflow and respond immediately
Send a follow-up message	Alt+Enter	Append a message after the agent finishes its work
Quit	Ctrl+C (press twice)	Exit Pi

Common commands include /model, /settings, /resume, /new, /tree (session-branch management), /compact (manually compact context), and /session.

A real-world cost example

A typical use case: crawling 285,000 URLs with DeepSeek v4 Flash took about 1.5 hours for a total cost of $1. This illustrates Pi’s cost advantage when paired with open-source models.

Why choose Pi

Pi’s core strengths come down to:

Terminal-native: no UI lag, responsive
Model-agnostic: switch providers anytime via /model, with seamless context migration
Highly customizable: the extension and package mechanism lets users assemble features on demand
Session-tree management: the /tree command supports branching and navigating conversation history
Automatic context compaction: automatically summarizes when approaching the context limit

For terminal users, Pi’s value lies not in “having the most features” but in “having the highest controllability.” Every one of its behaviors is transparent, and every feature is explicitly installed. This design philosophy makes it the ideal choice for side projects and experimental tasks.

Sources:

OpenClaw vs Hermes Agent: The Executor vs The Learner

Mon, 04 May 2026 15:57:59 +0800

OpenClaw and Hermes Agent are the two most-watched open-source self-hosted AI agent frameworks of 2026. Both support multi-platform messaging, tool calling, and persistent memory, but they differ fundamentally in core philosophy, architectural design, and evolution path. This article provides a comprehensive comparison based on their latest versions as of May 2026.

OpenClaw’s latest version is 2026.5.3 (released May 4, 2026), with a GitHub repo of 368k stars, 1,976 contributors, and 41,105 commits. Hermes Agent’s latest version is v0.12.0 “The Curator” (released April 30, 2026), with a GitHub repo of 132k+ stars, 822 contributors, and 7,150 commits.

Core Philosophy: Executor or Learner

The fundamental divergence lies in how each answers the question “what should an agent be?”

OpenClaw positions itself as an executor (Doer). It is a toolset you configure and run, executing tasks according to predefined skills and workflows. Its performance is essentially fixed the moment your configuration is complete — unless you manually modify config or skill files, it won’t change significantly with usage over time. As the community puts it: “OpenClaw stays exactly as it was the day you started using it.”

Hermes Agent positions itself as a learner. Its core design revolves around a repeatable “do, learn, improve” loop. After each complex task, Hermes extracts reusable patterns, automatically writes skill documentation, and invokes and refines these skills in subsequent similar tasks. According to publicly available information from Nous Research, this procedural memory mechanism improves Hermes’s execution efficiency on families of repeated tasks by roughly 40% within weeks.

This philosophical difference directly shapes the user-agent relationship: OpenClaw is more like a machine you program, while Hermes is more like a teammate who works with you — the longer you work together, the better you sync.

Architecture: Gateway-Centric or Loop-Centric

OpenClaw’s Gateway-Centric Architecture

OpenClaw uses a single Node.js process as its core; session management, routing, tool execution, and state storage are all concentrated in that process. Its architecture can be summarized as follows:

The advantage of this design is that deployment and debugging are extremely simple. You start one process, all logs live in one place, and there are no service-discovery or cross-container networking issues. For individual users and small teams, this “all-in-one” experience reduces operational overhead.

The cost is limited horizontal scalability. When concurrent task volume grows, you cannot scale a single subsystem independently — you must scale the whole thing up. Additionally, all components share the same address space, so a security flaw in one module can potentially impact the entire system.

Hermes Agent’s Loop-Centric Architecture

Hermes Agent designs all components around the AIAgent loop. According to Nous Research’s official architecture documentation, its core file run_agent.py is roughly 13,700 lines and contains three subsystems:

Prompt Builder: assembles system prompts, with built-in context compression and caching
Provider Resolution: supports three API modes (chat_completions, codex_responses, anthropic_messages)
Tool Dispatch: a tool registry managing 61 tools and 52 tool sets

Downstream systems include SQLite + FTS5 session storage, 6 terminal backends (local, Docker, SSH, Daytona, Singularity, Modal), and 19 messaging platform adapters.

Under this architecture, the learning loop is a first-class architectural concern rather than an afterthought. Every component exists to serve the core “observe, act, reflect, improve” flow. The cost is higher system complexity and some operational capability required from the user.

Skill Systems: Static Documentation or Self-Improving Programs

Skills are the core competitive differentiator of agent frameworks, and the two take completely different design approaches.

OpenClaw: Community-Driven Static Skills

OpenClaw skills exist as natural-language Markdown files (SKILL.md) hosted on the ClawHub marketplace. As of early 2026, ClawHub has over 5,700 community-contributed skills covering content creation, sales automation, data analysis, customer service, and more.

The benefit of this design is an extremely low barrier to entry. Even users without a programming background can define agent behavior by writing natural-language documents. The skill format is intuitive — similar to writing an operations manual.

But static skills have two clear limitations: first, performance does not improve automatically with usage — executing the same task each time repeats the same reasoning process; second, the quality of community skills is uneven. A Snyk audit in early 2026 found 1,467 malicious skills on ClawHub, 91% of which combined prompt injection with traditional malware techniques. OpenClaw was forced to introduce mandatory SkillFortify verification in version 2026.3.22, and direct installation of skills via GitHub URLs was removed.

Hermes Agent: Self-Improving Procedural Memory

Hermes Agent’s skill system is its most distinctive feature. Skills use the open agentskills.io standard format, but the key difference lies in how they are created and improved:

Stage	Behavior
Experience accumulation	Complete complex multi-step tasks
Pattern extraction	Identify reusable workflow patterns
Skill creation	Automatically write Markdown skill files
Skill refinement	Self-improve based on results during later use
Periodic review	Evaluate overall performance every 15 completed tasks

This mechanism lets Hermes’s skill library grow and improve naturally over time. A customer-service flow that took multiple rounds of interaction to complete in March can become a one-shot automated operation by June. Procedural memory stores “how to do” rather than “what was said” — this is the essential difference from simple conversation history.

Version v0.12.0 further introduced the “Curator” mechanism, which automatically rates and prunes the skill library to prevent low-quality skills from accumulating.

Memory Mechanisms: Conversation Archive or Layered Cognition

OpenClaw’s Memory Design

OpenClaw manages memory with plain Markdown files, including SOUL.md (agent personality), MEMORY.md (long-term memory), and USER.md (user profile). Search relies on a SQLite vector database and keyword matching.

The advantage is simplicity and transparency: users can open the Markdown files directly to view and edit the agent’s memory. The downside is that memories lack structured relationships, cross-session knowledge persistence requires manual configuration, and there is no automatic knowledge compression or summarization.

Hermes Agent’s Layered Memory Architecture

Hermes Agent uses a five-layer memory architecture:

Layer	Function	Storage
Persistent notes	Agent-curated cross-session knowledge	SQLite + files
Session history	Searchable conversation records	FTS5 full-text search
User modeling	Deep understanding of user preferences	Honcho dialectical modeling
Procedural memory	Reusable skill methods	Markdown files
Archive storage	Cold storage of old sessions	SQLite

The core advantage of this layered design is hot/cold separation. Frequently accessed memories (recent skills, user preferences) stay in the active context, while infrequently accessed history is compressed and archived — achieving long-term memory without significantly increasing token consumption. Since v0.7.0, the memory backend is also pluggable, supporting Honcho, vector databases, or custom storage.

Security Posture: Open by Default or Conservative by Default

CVE-2026-25253 in February 2026 was a turning point for OpenClaw’s security reputation. This unauthenticated remote code execution vulnerability (CVSS 8.8) led to tens of thousands of unpatched OpenClaw instances being compromised before a patch was released. The root cause lay in OpenClaw’s single-process architecture and overly broad default permissions: a flaw in a single HTTP listening endpoint was enough to bring down the entire system.

OpenClaw has since taken a series of remedial measures:

Mandatory ClawHub plugin verification starting 2026.3.22, banning direct GitHub URL installation
Introduced AgentWard runtime monitoring (eBPF probes)
Patched follow-up vulnerabilities such as CVE-2026-2847 (WebSocket hijacking)
The 2026.5.3 release further strengthened the plugin installation scanner and fixed the issue of officially bundled plugin packages being falsely blocked

But most of these improvements are after-the-fact remediation. OpenClaw’s default security posture still leans toward “trust the single-machine environment,” with sandboxing off by default.

Hermes Agent was designed with secure-by-default principles from the start:

Container hardening (read-only root filesystem, reduced privileges)
Five sandbox backends, with isolation enabled by default
Built-in prompt injection scanning
Sensitive-data context filtering
Credential file isolation

As of May 2026, Hermes Agent has no publicly recorded CVEs. It should be noted that any complex software is hard to keep completely free of vulnerabilities; Hermes’s architectural advantage is that isolation design confines the blast radius of a single vulnerability to a specific module, rather than preventing all vulnerabilities from occurring.

Feature-by-Feature Comparison

Dimension	OpenClaw 2026.5.3	Hermes Agent v0.12.0
Messaging platforms	25+	19 (incl. Teams, Yuanbao, QQBot, Home Assistant)
Terminal backends	2 (local, Docker)	6 (local, Docker, SSH, Daytona, Singularity, Modal)
Built-in tools	Depends on skills/plugins	40+
Subagents	Supported	Isolated subagents (separate session, terminal, Python RPC)
MCP support	Client	Client + Server mode
Scheduled tasks	Heartbeat cron	Built-in Cron scheduler
Model providers	OpenAI, Anthropic, Google, OpenRouter	Nous Portal (400+), OpenRouter (200+), OpenAI, Anthropic, Gemini, Bedrock, Xiaomi MiMo, etc.
RL/research support	None	Atropos integration, batch trajectory generation
Voice/TTS	ElevenLabs, Edge TTS, macOS system TTS	Supported
Browser automation	Playwright	Camofox (10 browser tools)
Local LLMs	Ollama, llama.cpp, vLLM	Ollama, llama.cpp, vLLM
Installation	npm install -g openclaw	brew install or pip install
Resource requirements	8GB RAM minimum	8GB RAM minimum
Real-time voice	Supported (macOS/iOS wake word + Android continuous voice)	Supported
Visual Canvas	Live Canvas (agent-driven visual workspace)	None
File transfer	File transfer plugin (16MB per-round cap, symlink traversal denied by default)	Built-in file tools

Installation and Getting Started

OpenClaw’s installation experience is closer to a consumer app. After running openclaw onboard --install-daemon, the interactive wizard automatically creates a workspace, generates persona files, configures API keys, and guides messaging platform integration. Going from cold start to a working agent usually takes 3 to 5 minutes.

Hermes Agent’s installation requires some technical background. Although hermes init provides interactive configuration, users still need to understand concepts like Docker networking and service topology. For DevOps engineers who routinely deploy containerized systems, this transparency and controllability is an advantage; for users who have never configured a .env file, it can be a barrier.

Recommendations

Use case	Recommended choice
Fastest deployment, largest integration list, broadest community	OpenClaw
Want the agent to grow more efficient with usage	Hermes Agent
Migrating from OpenClaw (especially after security incidents)	Hermes Agent (built-in hermes claw migrate)
Fully offline with local models	Either
Non-technical background, wants out-of-the-box	OpenClaw
Enterprise deployment needing security isolation and scalability	Hermes Agent
Researchers needing RL training and trajectory data	Hermes Agent
Prompt engineers who prefer hand-writing SKILL.md	OpenClaw
Need real-time voice wake word and visual Canvas	OpenClaw

Sources

The information in this article comes from the following public channels:

OpenClaw official GitHub repository — openclaw/openclaw, 368k stars, 1,976 contributors, 41,105 commits, MIT license
OpenClaw official Releases page — latest version 2026.5.3 (May 4, 2026)
OpenClaw official docs — docs.openclaw.ai
Hermes Agent official GitHub repository — NousResearch/hermes-agent, 132k+ stars, 822 contributors, 7,150 commits, MIT license
Hermes Agent official architecture docs — Nous Research, 2026
Lushbinary: Hermes vs OpenClaw key differences — April 7, 2026
Lushbinary: Hermes Agent developer guide — April 7, 2026
DeployAgents: OpenClaw vs Hermes deep comparison — April 9, 2026
Amir Teymoori: Hermes Agent vs OpenClaw comparison — 2026
NVD: CVE-2026-25253 — U.S. National Vulnerability Database

Limitations and Disclaimer

This article is compiled from public information available as of May 2026. Some performance figures (such as Hermes’s 40% efficiency improvement) come from public statements by the project team and have not been verified by independent third-party benchmarks.

Both OpenClaw and Hermes Agent are in a period of rapid iteration, and some features may have changed by the time you read this. We recommend consulting each project’s official docs and latest release notes before making a final decision.

Neither offers an enterprise-grade zero-trust sandbox. For regulated industries such as finance and healthcare, we recommend additional security assessment and compliance review before adoption.

This article is compiled from publicly available community discussions and official documentation and does not constitute professional procurement or security advice.

Pi Coding Agent: A Terminal AI Coding Agent Built on 418 Lines of Code

Wed, 29 Apr 2026 02:07:14 +0800

Pi (full name pi-coding-agent) is an open-source terminal AI coding agent (a CLI coding harness). It has accumulated more than 17,500 stars on GitHub, with peak npm weekly downloads of 1.3 million. It was developed by Mario Zechner (author of the well-known game framework libGDX, GitHub @badlogic), and recently ranked first on OpenRouter’s trending list.

Core philosophy: minimalism and extensibility

Pi was born out of Zechner’s dissatisfaction with existing coding agents. As he wrote on his blog: “Claude Code has turned into a spaceship — I don’t use 80% of its features. The system prompt and tools change with every release, breaking my workflow.”

Pi’s philosophy can be summed up as: “If I don’t need it, I don’t build it.”

Compared with similar tools, Pi chooses extreme minimalism on multiple dimensions:

Dimension	Mainstream tools like Claude Code	Pi
Core agent loop	Thousands of lines of code	418 lines of TypeScript
System prompt + tool definitions	Thousands of tokens	< 1,000 tokens
Default tools	A dozen or more	4 (read, write, edit, bash)
Built-in features	Big and comprehensive	Minimal, filled out with extensions

Zechner’s core assumption: all frontier models have been heavily trained with RL, so they already understand what a coding agent is. Therefore the harness doesn’t need to over-instruct the model — the lighter the better.

Four-layer architecture

Pi uses a strictly bottom-up layered design, with each layer having zero dependency on the layers above it:

pi-ai: cross-provider context migration

pi-ai is the low-level unified LLM API, supporting 15+ providers and 300+ models. It normalizes four protocols — OpenAI Completions, OpenAI Responses, Anthropic Messages, and Google Generative AI — into a unified event-stream format.

Its killer feature is cross-provider context migration: in a single session you can think with Claude first, then switch to GPT-4o to verify, with the context carried over seamlessly. Claude’s thinking traces are automatically converted into `` tags for OpenAI models to read.

pi-agent-core: the 418-line dual loop

This is Pi’s core, using a two-layer separation of AgentMessage (application layer) and LLM Message (model layer):

No maximum step limit: the loop keeps running until the agent itself declares completion
Runtime hot-swapping: setModel(), setTools(), setSystemPrompt() take effect at any time
Steering mechanism: users can send “steering messages” while the agent is executing tools; the agent responds as soon as it finishes the current tool, skipping the remaining queued tool calls
Three-tier event system: full streaming event subscription at the agent / turn / message / tool level

pi-coding-agent: the terminal application layer

Provides four operating modes:

Mode	Use case
Interactive	Full TUI interaction experience
Print (-p)	Generate a shell script and print it
JSON (–mode json)	Structured event stream, good for pipelining
RPC (–mode rpc)	JSON protocol over stdin/stdout, embeddable in other applications
SDK	Embed directly into Node.js applications

Extensibility: Pi’s real killer feature

Pi turns “features built into other tools” into “extensions you build or install yourself” — this is its most fundamental difference from tools like Claude Code.

Extensions: TypeScript modules with access to tools, commands, shortcuts, events, and the full TUI
Skills: on-demand capability packages (instructions + tools)
Prompt Templates: reusable Markdown prompts expanded quickly with /name
Pi Packages: extension packages distributed via npm or git

The official repo offers 50+ extension examples, including subagents, plan mode, permission gating, path protection, SSH execution, sandboxing, and MCP integration.

Context-engineering mechanisms

Pi provides multiple mechanisms for precise context control:

Mechanism	Use case
AGENTS.md	Project-level instructions, placed in ~/.pi/agent/ or the project directory
SYSTEM.md	Replace or append to the default system prompt
Compaction	Automatically summarizes near the context limit; customizable
Dynamic Context	Inject messages, filter history, RAG, and long-term memory via extensions

Community positioning and the Harness Effect

According to a six-harness comparison released by Pawel Jozefiak in April 2026, Pi’s positioning is that of a moldable, minimal harness.

The review proposed an important “Harness Effect”: the same model can differ by 5–40 percentage points across different harnesses. For example, Claude Opus scores 77% in Claude Code but reaches 93% in Cursor. Pi’s value is that it provides a highly tunable, fully transparent foundation, letting users optimize this effect for themselves.

Tool	Positioning	Characteristics
Claude Code	Agent Orchestrator	Strongest contextual coherence; suited to complex multi-file tasks and unattended overnight runs
Codex CLI	Coding Tool	Executes cleanly but lacks contextual coherence
Aider	Coding Tool	High editing precision, but doesn’t aim to be an autonomous agent
OpenCode	Middle ground	Built by the SST team; feature-complete
Pi	Moldable minimal harness	Lightweight, transparent, deeply customizable

What can you use it for

Everyday coding agent: a replacement for Claude Code / Codex CLI, handling code generation, refactoring, and debugging in the terminal
Custom workflows: build your own “plan mode”, “permission gating”, and “subagent orchestration” via extensions
Embedding in other applications: use Pi as an engine inside your own tools via the SDK or RPC mode (OpenClaw takes this approach)
Multi-model collaboration: switch between different models within a single task, leveraging each one’s strengths
Overnight autonomous runs: combine the steering and follow-up mechanisms for long-running autonomous tasks
Team standardization: share coding conventions and workflows across a team through AGENTS.md, Skills, and Pi Packages

Quick start

Pi’s install and launch flow is extremely simple.

Installation

Launch it after entering your project directory:

Adding a model (authentication)

Pi supports two authentication methods:

Method 1: subscription login

Run this inside Pi’s interactive interface:

Then choose a provider. Built-in support includes Claude Pro/Max, ChatGPT Plus/Pro (Codex), GitHub Copilot, and Google Gemini CLI.

Method 2: API key

Set the environment variable before launching:

You can also choose an API-key provider via /login, storing the key in ~/.pi/agent/auth.json.

Task conversations

After launching, just type what you need:

Four tools are provided by default: read (read files), write (write files), edit (edit files), and bash (run commands). Read-only tools like grep, find, and ls can be enabled via options.

Common operations:

Reference a file: type @ for fuzzy search, or specify directly on the command line: pi @README.md "Summarize this"
Run a command: !npm run lint (send output into the model’s context), !!command (run without sending into context)
Switch models: /model or Ctrl+L
Continue sessions: pi -c (most recent session), pi -r (browse history), /resume, /new, /tree (session management)
Non-interactive mode: pi -p "Summarize this codebase" (single-shot output)

Project instructions

Create an AGENTS.md in the project root, which Pi loads automatically at startup:

Run /reload after modifying it for changes to take effect.

Summary

Pi is not “yet another Claude Code replacement.” It is a radical minimalist experiment, proving that a well-designed lightweight harness can match or even surpass complex frameworks.

It’s best suited to developers dissatisfied with the “black-box behavior” of existing agents, and to advanced users who want full control over the system prompt, tools, and context flow. If all you want is an “out-of-the-box, feature-complete” experience, Claude Code may remain the first choice; but if you want to understand and control every line of behavior in your agent, Pi is one of the most transparent options available today.

Sources

Processing Scanned PDFs: From Local OCR to Vision Language Models

Sat, 11 Apr 2026 12:54:28 +0800

A common pitfall when handling scanned PDFs is to run a full pass with traditional OCR tools first, then spend a lot of time cleaning up the erroneous results. This article draws on a large scanned-PDF extraction task executed by Hermes Agent and abstracts a more general processing logic: how to complete the recognition and structured organization of scanned PDFs efficiently and with high quality at minimal sunk cost.

1. First, Decide: Is It an “Image Book” or a “Document”?

The first step after getting a PDF is not to extract directly, but to detect its type. Many scanned PDFs look like a .pdf on the surface yet contain no extractable text layer inside.

This step usually only takes a few seconds, but it can prevent hours of wasted subsequent effort.

2. The Role of Local OCR Should Be Minimized

Once you confirm it is an image-based PDF, many people’s second reaction is to fire up a traditional OCR tool such as Tesseract and run full recognition and cleanup. In real tasks, however, the marginal benefit of this approach is often low:

Local OCR handles printed English reasonably well, but it is error-prone on Chinese definitions in mixed Chinese-English layouts;
Cleanup scripts can only deal with layout noise (headers, footers, table lines), not semantic-level recognition errors;
When the end goal is structured, directly usable, high-quality text, investment in cleanup code can easily become a sunk cost.

3. The Decisive Step: Bringing in a Vision Language Model for Direct Recognition

In this task, once Hermes Agent confirmed that the local OCR output for Chinese was unacceptable, it wrote its own Python script and directly called an external Vision-Language model (Qwen/Qwen2-VL-72B-Instruct) to re-recognize the content. This was the turning point that ultimately determined output quality.

3.1 Lessons from Model Selection

The initial test used a dedicated model named OCR, but that model had weak instruction-following capabilities—it repeatedly output the review tables and marking symbols from the page and could not extract only the target content as required. This shows that:

3.2 Secure Practices for API Calls

The external API key was not hardcoded into the script; it was injected via environment variables configured in ~/.hermes/.env (such as SILICONFLOW_API_KEY), read by the script through os.environ. This practice meets security requirements:

The key is not exposed in any code file or log;
Credentials are stored in a controlled config location in the user’s home directory;
It is only valid for the lifespan of the current session.

For an AI agent, retrieving environment variables through ~/.hermes/.env is the standard and secure way to call external services.

4. Page Stitching Strategy: Merge Consecutive Pages and Recognize Them Together

Scanned books, textbooks, and exam papers often contain content that flows continuously across pages. If each page is uploaded separately to the model, it can lead to:

Fragmented context, causing the model to misjudge the relationship between content on two pages;
Cross-page items being truncated or missed.

The strategy used in this task was:

Specific steps:

Use pdf2image to convert consecutive pages into images;
Use PIL to stitch multiple images vertically into one long image;
Compress as JPEG, encode as base64, and upload via the API.

The advantage of this approach is that it preserves the continuity and spatial relationships of reading, reduces context switching during API calls, and also saves the overhead of multiple requests.

5. Prompt Design: Hard Constraints for Structured Output

To get the Vision model to output clean text that can be written directly to a file, the prompt needs to include the following hard constraints:

Explicit exclusions: List all non-target content on the page (tables, circle markings, page numbers, usage instructions, etc.), and require the model to actively ignore them;
Format template: Specify the output format for each entry, for example number. English word phonetic part-of-speech Chinese definition;
Fixed header: Force the output to begin with a unified heading structure to make downstream automation easier;
Reference text aid: Append the initial local OCR results to the end of the prompt, letting the model do “comparative correction” based on the image rather than guessing blind from scratch. This significantly improves output accuracy and completeness.

6. Core Methodology: Verify First, Then Run in Full

Whatever toolchain you use, the most important step when handling scanned PDFs is:

6.1 What to Verify with Minimal Effort

Before launching a full batch process, the agent should first verify the following elements at minimal cost:

Page-number mapping pattern: How many days/chapters? How many pages per chapter? Where are the boundaries?
Model recognition ability: At the current DPI, can the model accurately recognize fonts, phonetic symbols, and mixed Chinese-English content?
Prompt stability: Is the output format consistent across 1–3 consecutive samples? Is any content missing?
Cost estimate: Is the token consumption per page/chapter within budget? Can the DPI be downgraded?

6.2 Dynamic Resolution Scaling

Image token cost is roughly proportional to resolution. You can first test the Vision model at a low DPI (such as 100 DPI); if the recognition rate is already sufficient, there is no need to use 150 DPI or 250 DPI. For printed materials with large fonts, 100 DPI is often enough, reducing image encoding cost by about 50% or more.

6.3 Possibility of Structured Output

If the API supports JSON mode, you can ask the model directly to return a structured array (such as {"word", "phonetic", "pos", "definition"}), entirely eliminating post-processing cleanup code and improving automation and maintainability.

7. Delivery Structure: Keep Raw Data and Refined Results Separate

For tasks that may produce multiple versions of results, a dual-directory isolation design is recommended:

The benefits of this design:

Raw data is not lost;
The refined result of any unit can be diffed against the original output;
Rollback is always possible because nothing is overwritten.

8. Pre-Flight Checklist for AI Agents

If you are an AI agent and receive a task to “extract structured content from a scanned PDF”, follow this order:

PDF type detection: sample with pdfinfo + pdftotext to confirm whether it is an image-based PDF;
Structure-pattern detection: use the lowest-cost method (low-resolution OCR or a small number of Vision API calls) to confirm the “page → chapter/unit” mapping pattern;
Solution validation: process the first 1–3 units with the Vision model to verify output format, completeness, and accuracy;
API key security: read it from ~/.hermes/.env environment variables, never hardcode it;
Full concurrent execution: run the batch only after confirming everything works, saving results to a separate directory without overwriting the raw data.

9. Conclusion

For content extraction from scanned PDFs, the order in which you choose your toolchain matters more than the capability of any single tool. Traditional OCR is well-suited as a low-cost structural-probe sentinel, but if the goal is directly usable, high-quality structured text, a Vision-Language model is the ultimate guarantee of quality.

The most expensive mistake is usually not picking the wrong model, but launching a full batch process without minimal verification first. Agents should establish a rhythm of “validate a sample → adjust parameters → run the full batch” early on, to control sunk costs and ensure the reliability of the final deliverable.

API Keys Don't Belong in Your Shell Config Files

Tue, 07 Apr 2026 03:11:16 +0800

API keys should not live in your shell config files. It’s a habit many developers have, chosen for convenience, but the risk has been underestimated for a long time.

A recent operational mistake brought this home for me: a command couldn’t find its target file, so the fallback ran env, dumping the entire terminal environment variables out. A dozen API keys went straight into an AI conversation’s context, and I had to rotate all of them.

The incident was small, but it revealed a structural problem: keeping keys in shell config files means they are always exposed to every child process and every tool’s view.

Why shell config files aren’t a good place for API keys

Different shells have different config files, but they all face the same problem:

zsh: ~/.zshrc, ~/.zprofile
bash: ~/.bashrc, ~/.bash_profile, ~/.profile
fish: ~/.config/fish/config.fish

Writing export API_KEY=xxx in these files has these consequences:

Every terminal session loads them automatically at startup, so any child process can read them
Commands like env and printenv can reveal the plaintext at any time
AI tools, log collectors, and debug output may accidentally capture them
If the config file gets synced to a dotfiles repo, they become public directly

The root problem is: the key’s lifetime is far longer than the time it’s actually used.

Better approaches

Option one: project-level `.env` + precise injection

The lightest improvement. Each project only holds the keys it uses, extracted precisely via a script without polluting the global environment.

run.sh example:

Pros: simple, no dependencies, works on every operating system.

Cons: the key still sits on disk in plaintext.

Option two: macOS Keychain

System-level encrypted storage. The key is stored encrypted in the Keychain and only decrypted into memory at the moment it’s read; cat, grep, and env can’t see it.

Storing:

Reading in a script:

Experience: When you log into your Mac, the system Keychain unlocks automatically, so scripts can read values directly for the whole session without asking for a password. The first time you access an item, the system shows a single authorization dialog; click “Always Allow” and it never appears again.

This is the most direct replacement for storing keys in shell config files, and it has almost no impact on your workflow. It’s macOS-only; Linux and Windows have their own equivalents (secret-tool, Windows Credential Manager).

Option three: Bitwarden CLI (self-hosted)

If you have a Bitwarden instance (including a self-hosted Vaultwarden), you can use the official CLI, bw, to pull keys dynamically within scripts.

Configuring the self-hosted address:

Logging in and getting a session:

The session stays valid within the current terminal session and expires when you close the terminal, so it isn’t persistently exposed.

Reading a specific entry in a script:

bw get password looks up an entry by name and returns its password field. You can also use bw get notes to fetch the notes field, which is handy for keys with complex stored formats.

Best fit: scenarios where multiple devices share the same set of keys, or where you need cross-platform support (macOS/Linux/Windows are all supported). Keys are centralized in Bitwarden, so switching devices only requires logging in again rather than manually migrating .env files.

Migration suggestions

If your shell config files currently hold lots of export KEY=xxx:

Organize by project; give each project its own .env with only the keys that project uses
Migrate high-value credentials (database passwords, payment-related) to Keychain or Bitwarden
Remove all the export KEY= lines from your shell config files
Make sure .env files are added to .gitignore

You don’t have to do everything at once. Migrate the most sensitive ones first, and move the rest as you touch each project.

Summary

Approach	Plaintext on disk	Cross-platform	Cross-device	Dependency
Shell config files	✓ (dangerous)	✓	Manual sync needed	None
Project `.env`	✓	✓	Manual sync needed	None
macOS Keychain	✗	✗	✗	Built into the system
Bitwarden CLI	✗	✓	✓	bw CLI

There’s no perfect solution, but any of these is better than shell config files. The most pragmatic starting point is: clear the keys from your config files and switch to project-level .env, then gradually move high-value credentials to Keychain or Bitwarden.

Technical Architecture on TorchTree

Pi Coding Agent in Practice: A Complete Guide from Installation to Everyday Use

Positioning: Pi’s role in the toolchain

Installation and first-time configuration

Three core extension packages

pi-web-access

pi-codex-goal

pi-vision-proxy

The configuration-file system

Shortcuts and common commands

A real-world cost example

Why choose Pi

OpenClaw vs Hermes Agent: The Executor vs The Learner

Core Philosophy: Executor or Learner

Architecture: Gateway-Centric or Loop-Centric

OpenClaw’s Gateway-Centric Architecture

Hermes Agent’s Loop-Centric Architecture

Skill Systems: Static Documentation or Self-Improving Programs

OpenClaw: Community-Driven Static Skills

Hermes Agent: Self-Improving Procedural Memory

Memory Mechanisms: Conversation Archive or Layered Cognition

OpenClaw’s Memory Design

Hermes Agent’s Layered Memory Architecture

Security Posture: Open by Default or Conservative by Default

Feature-by-Feature Comparison

Installation and Getting Started

Recommendations

Sources

Limitations and Disclaimer

Pi Coding Agent: A Terminal AI Coding Agent Built on 418 Lines of Code

Core philosophy: minimalism and extensibility

Four-layer architecture

pi-ai: cross-provider context migration

pi-agent-core: the 418-line dual loop

pi-coding-agent: the terminal application layer

Extensibility: Pi’s real killer feature

Context-engineering mechanisms

Community positioning and the Harness Effect

What can you use it for

Quick start

Installation

Adding a model (authentication)

Task conversations

Project instructions

Summary

Processing Scanned PDFs: From Local OCR to Vision Language Models

1. First, Decide: Is It an “Image Book” or a “Document”?

2. The Role of Local OCR Should Be Minimized

3. The Decisive Step: Bringing in a Vision Language Model for Direct Recognition

3.1 Lessons from Model Selection

3.2 Secure Practices for API Calls

4. Page Stitching Strategy: Merge Consecutive Pages and Recognize Them Together

5. Prompt Design: Hard Constraints for Structured Output

6. Core Methodology: Verify First, Then Run in Full

6.1 What to Verify with Minimal Effort

6.2 Dynamic Resolution Scaling

6.3 Possibility of Structured Output

7. Delivery Structure: Keep Raw Data and Refined Results Separate

8. Pre-Flight Checklist for AI Agents

9. Conclusion

API Keys Don't Belong in Your Shell Config Files

Why shell config files aren’t a good place for API keys

Better approaches

Option one: project-level .env + precise injection

Option two: macOS Keychain

Option three: Bitwarden CLI (self-hosted)

Migration suggestions

Summary

Option one: project-level `.env` + precise injection