Productivity Tools on TorchTree

Advanced Pi Agent Configuration: AGENTS.md, Model Switching, and Thinking Levels in Practice

Wed, 22 Jul 2026 12:14:08 +0800

In the article Pi Coding Agent in Practice: From Installation to Everyday Use, I covered Pi’s installation, first-time configuration, and its core extension packages. That content lets beginners get up and running quickly, but Pi’s real flexibility lives in its configuration files.

Pi’s core is just 418 lines of TypeScript, and by default it only gives the model four tools (read, write, edit, bash). All of its advanced behavior — which model to use, how large a context, how deep to think — is controlled through external configuration files. Understanding how these files relate to each other and how they’re prioritized is the key step in taking Pi from “usable” to “actually good.”

How many layers does Pi’s configuration have, and what does each one manage?

Pi’s configuration system uses a layered, additive design. Once you understand what each layer is responsible for and its order of precedence, you won’t run into “I changed it but nothing happened.”

Global configuration lives in ~/.pi/agent/, affecting all projects. Project configuration lives in a project’s .pi/settings.json, affecting only the current project. Nested objects in the project config are merged with the global config rather than replacing it entirely.

Beyond the two layers of settings.json, Pi also uses four specialized configuration files, each with a different purpose:

Config file	Location	Purpose	Load timing
AGENTS.md	Project root or ~/.pi/agent/	Project context and coding instructions, injected into the system prompt	Auto-loaded at startup
APPEND_SYSTEM.md	~/.pi/agent/	Global behavior rules, appended to the end of the system prompt	Loaded at startup
settings.json	Global or .pi/	Model selection, UI theme, compaction strategy, retries, and other runtime parameters	Loaded at startup
models.json	~/.pi/agent/	Custom models and Providers (Ollama, vLLM, etc.)	Reloaded each time you open /model
auth.json	~/.pi/agent/	API keys and OAuth credentials (permission 0600)	Read on demand

Below I’ll break down best practices for each configuration file in turn.

How to write an AGENTS.md that actually works

AGENTS.md is the primary entry point for Pi to understand a project’s context. When Pi starts, it looks in several locations and merges their contents into the system prompt: it loads ~/.pi/agent/AGENTS.md first (global instructions), then walks up through parent directories, and finally loads the AGENTS.md in the current directory.

In other words, the global AGENTS.md defines your typical tech stack and general conventions as a developer, while the project AGENTS.md defines that specific project’s constraints and workflow.

What to put in the global AGENTS.md

The global ~/.pi/agent/AGENTS.md is a good place to record the tech-stack preferences you use day to day. The global AGENTS.md that DeepakNess shares on his blog is a great reference example:

This content comes from DeepakNess’s article, Setting Up and Using the Pi Coding Agent. It doesn’t try to be overly specific — instead it gives broad tech-stack hints while asking Pi to defer to the project-level AGENTS.md first.

How to organize a project AGENTS.md

The project-level AGENTS.md needs to be more precise. Here’s a template tailored for a TypeScript project, based on the recommendations in the official Pi documentation:

If you manage multiple projects, it’s worth keeping a template for each project type. Copy it over each time you start a new project and adjust the tech-stack fields as needed.

Remember to reload after changes

Every time you modify AGENTS.md, you need to run /reload or restart Pi for the change to take effect. This operation isn’t triggered often, but it’s easy to forget. It’s best to test immediately after writing a new rule to confirm Pi’s behavior changed as expected.

What does APPEND_SYSTEM.md control?

~/.pi/agent/APPEND_SYSTEM.md is appended to the end of the system prompt, and it takes precedence over AGENTS.md. This means its instructions override what came before.

It’s a good fit for defining behavioral guidelines that apply across projects, especially constraints about how the agent works and how it interacts with the user. Drawing on official recommendations and community practice, a typical APPEND_SYSTEM.md looks like this:

These rules ensure Pi maintains a consistent way of working across projects, without having to restate everything at the start of every conversation.

settings.json: common options explained

settings.json has two layers: global (~/.pi/agent/settings.json) and project (.pi/settings.json). Nested objects in the project layer merge with the global layer. Drawing on the official Pi Settings documentation, here are the settings most worth knowing:

Models and thinking levels

defaultProvider and defaultModel control the model Pi uses by default at startup. defaultThinkingLevel sets the thinking depth, with options including off, minimal, low, medium, high, xhigh, and max.

enabledModels is a high-impact setting. It defines the list of models cycled through by Ctrl+P, and supports wildcards. If you leave it unset, Ctrl+P iterates over every available model for that provider, which hurts the experience significantly.

thinkingBudgets lets you customize the token budget for each thinking level. The numbers above follow the defaults given in the official Pi documentation. Whether to adjust them depends on your model and task: the higher the budget, the deeper the thinking, and the more tokens consumed.

Context compaction

Compaction is Pi’s core mechanism for handling long contexts. When the session approaches the context limit, Pi automatically summarizes older messages to free up space for subsequent conversation.

reserveTokens: the number of tokens reserved for the LLM’s response (default 16384). The smaller this value, the sooner compaction happens.
keepRecentTokens: the number of recent tokens kept without being summarized (default 20000). Kept messages stay intact, ensuring the most recent discussion isn’t lost.

If you regularly handle long sessions, you can raise keepRecentTokens. Note, though, that this reduces compaction efficiency and may hit the model’s context-window ceiling sooner.

Retry strategy

The retry configuration is split into two layers: agent-level retries (handled by Pi itself) and provider-level retries (handled by the API SDK). The official documentation recommends keeping retry.provider.maxRetries at 0, because provider-level retries can burn quota before you even see a rate-limit error.

baseDelayMs controls the initial delay of exponential backoff: 2s → 4s → 8s. For tasks that need to run stably over a long time (for example, batch data crawling), you can reasonably increase this value.

Project trust mode

When Pi first starts in a project, it asks whether to trust that project’s .pi/ directory. This mechanism exists to prevent malicious project plugins from auto-loading.

Available values include ask (ask every time, the default), always (auto-trust), and never (never trust). In CI or automation scenarios, you can use the -a / --approve flag to skip the prompt.

Adding custom models with models.json

If your model isn’t among Pi’s built-in 20-plus Providers, you can add it via ~/.pi/agent/models.json. This file supports Ollama, LM Studio, vLLM, OpenRouter, Cloudflare AI Gateway, and any OpenAI-compatible API endpoint.

Referencing the full configuration notes in the official Pi Models documentation, here are the three most common scenarios:

Scenario 1: a local model via Ollama

apiKey being set to "ollama" is just a placeholder. Ollama doesn’t validate the API key, but Pi needs an auth value to show the model in /model. The two switches under compat target Ollama’s characteristics: it doesn’t support the developer role or the reasoning_effort parameter.

The name field gives a human-readable label. Pi uses this value both in the model selector and when matching the --model mode.

Scenario 2: OpenRouter routing configuration

OpenRouter lets you set routing preferences among multiple API providers. The configuration below follows the OpenRouter example in the official Pi documentation:

The openRouterRouting object is passed through verbatim to the provider field of the OpenRouter API. order specifies provider priority, and data_collection: "deny" declines to use your data for training.

Scenario 3: proxying the Anthropic API

If you use a third-party proxy for the Anthropic Messages API, you can configure it like this:

In models.json, apiKey and headers support three value-resolution modes: a direct literal, $ENV_VAR environment-variable interpolation, or !command command execution. Bitdoze notes in the Pi Coding Agent Setup Guide that Pi supports Ollama, LM Studio, vLLM, and any OpenAI-compatible endpoint. This extensibility is a major advantage over comparable tools.

Managing API credentials with auth.json

~/.pi/agent/auth.json stores the API keys and OAuth tokens for all providers. Its permission is set to 0600, allowing only the current user to read and write it.

auth.json supports three ways of resolving keys:

Literal: use the API key string directly
Environment-variable interpolation: "$MY_KEY" or "${KEY_PREFIX}_${KEY_SUFFIX}"
Shell command: "!security find-generic-password -ws 'anthropic'"

The official documentation notes that auth.json takes precedence over environment variables. This means if you’ve set both a DEEPSEEK_API_KEY environment variable and a deepseek entry in auth.json, the latter overrides the former.

One practical tip is to use a shell command to read the credential from the system keychain, avoiding writing your API key in plaintext to any file:

Model-switching strategy: which model to use when

One of Pi’s core strengths is model-agnosticism. You can pick a different model for different tasks, and switching is instantaneous.

How to switch

Action	Shortcut / command	Notes
Open the model selector	Ctrl+L or /model	Quickly switch models
Cycle through models	Ctrl+P	Rotate through the enabledModels list
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
Reference a file	@	Fuzzy-search files
Run a command	!	Send a command’s output to the model
Silent command	!!	Run a command without adding it to context

The shortcut table partly draws on the Pi Agent Chinese guide and DeepakNess’s setup article.

A recommended layered strategy

Experience from multiple community users converges on the same pattern: use models in layers, matching capability to task complexity. The following is drawn from DeepakNess and Bitdoze’s articles:

Task type	Recommended model	Thinking level	Reasoning
Quick edits, file operations, batch scripts	DeepSeek V4 Flash / MiniMax M2.7	low or off	Extremely cheap, plenty for fast tasks
Everyday coding, small-to-medium refactors	DeepSeek V4 Pro / Qwen 3.6 Plus	medium	Balances quality and cost
Deep analysis, architecture design, complex debugging	DeepSeek V4 Pro / Claude Sonnet 4	high or xhigh	Needs a deeper reasoning chain
Visual tasks (screenshot understanding, UI analysis)	Kimi K3 / Claude	depends on the model	Proxied via pi-vision-proxy when the main model has no vision

DeepakNess provides a concrete data point in his article: crawling 285,000 URLs with DeepSeek V4 Flash took about 1.5 hours with a total cost of $1. That illustrates the cost-effectiveness of low thinking level plus a cheap model on batch tasks.

enabledModels wildcards

To make Ctrl+P switching more efficient, it’s worth setting an enabledModels list in settings.json:

Wildcards match all qualifying models. If you only need two or three specific models, you can also write exact IDs:

How Thinking Level affects output quality

Pi’s thinking level is a layered parameter that controls how deeply the model reasons before answering. Based on the official Settings docs at pi.dev and the thinkingLevelMap explanation in models.md, different levels correspond to different behavioral characteristics:

Level	Use case	Token budget (default)
off	Simple Q&A, tasks that need no reasoning	no reasoning tokens
minimal	Very simple judgments, such as “yes/no” classification	1024
low	Light reasoning, e.g. formatting, simple conversions	4096
medium	Routine coding tasks	10240
high	Complex refactors, debugging	32768
xhigh	Deep analysis, architecture design	65536
max	Extremely complex multi-step reasoning	provider cap

The differences between levels aren’t linear. The biggest quality gain is from low to medium; from high to xhigh, the marginal returns diminish. In practice, 80% of everyday tasks get satisfactory results at the medium level.

For models that support thinkingLevelMap, you can finely control in models.json which provider-side parameter each level maps to. For example, a given model might only need the high and max levels, with the middle levels skipped:

This mechanism comes from the thinkingLevelMap explanation in the Pi Models documentation. When a model doesn’t support certain levels, Pi automatically jumps to the adjacent supported level.

Context management: compaction, session trees, and manual control

Long sessions are the norm for coding agents. Pi provides three layers of context-management mechanisms.

Automatic compaction

Compaction runs in the background. When the context approaches the model’s window limit, Pi automatically summarizes older messages. compaction.reserveTokens controls when compaction triggers: it fires when the remaining tokens drop below this value. compaction.keepRecentTokens ensures the most recent messages aren’t summarized.

If you want finer control, you can trigger /compact manually and Pi will immediately compact the current session.

Session-tree management

The /tree command displays the session history as a tree structure. Each branch represents a conversation path. Pi supports:

/resume: pick up a previous session and continue working
/new: start a new session
/fork: branch from the current session to begin a new line of conversation

This design lets you try different solution paths without losing context.

A complete configuration template

Combining all of the above, here’s a complete configuration you can put into daily use.

Global settings.json

Global APPEND_SYSTEM.md

Project .pi/settings.json (overriding the global compaction strategy)

This override makes short-session projects that need frequent compaction trigger it earlier, avoiding wasted context window.

Summary

Pi’s configuration system revolves around one core principle: layer on layer, precise control. Global configuration defines general behavior, project configuration overrides specific needs, AGENTS.md conveys project context, and APPEND_SYSTEM.md constrains the agent’s behavioral patterns.

Once you understand what each layer is responsible for and its priority, Pi’s “minimal core + external configuration” design philosophy stops being a “too few features” weakness and becomes a “you control everything” strength. When facing different tasks each day, you only need to switch models with Ctrl+P and adjust thinking depth with Shift+Tab to move quickly between different working modes.

If your configuration already covers the main files mentioned in this article, the next step is to focus on the extension system: use pi install to add packages such as pi-web-access (web search), pi-codex-goal (task tracking), and pi-vision-proxy (vision proxy), gradually building a Pi environment fully suited to your own workflow.

Sources:

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:

Why Warp Went Open Source and What It Means

Wed, 29 Apr 2026 03:32:22 +0800

On April 28, 2026, Warp’s official blog announced that its terminal client is now open source under the AGPL license, with the code hosted on GitHub. This decision is not merely a code release; it comes with a collaboration mechanism called the Agent-first Workflow, where community contributors work alongside AI Agents via Warp’s own Oz platform to drive development. OpenAI participated in the experiment as a founding sponsor.

This article analyzes Warp’s open-source motives, the impact on users, the differences between the free and paid tiers, and the product’s future direction, based on Warp’s official announcements and pricing information.

What Is Warp

Warp is a modern terminal application for developers, with core features including block-based command editing, autocompletion, history search, and AI-based Agent-assisted programming. Beyond the terminal client, Warp has also launched product lines including Agents (multi-Agent deployment and tracking), Code (building complex features in production codebases), Drive (knowledge base and context management), and Oz (cloud Agent orchestration platform).

Before the open-source move, Warp’s terminal client was closed source, with AI features billed by usage. After open-sourcing, the terminal client code is public under the AGPL license, but AI capabilities and cloud services remain paid.

Why Warp Chose to Open Source Now

Warp’s official blog gives two levels of reasons.

The primary reason is a bottleneck shift in development efficiency. In traditional software development, coding itself is often the most time-consuming part. But as AI Agent capabilities improve rapidly, the Warp team found the limiting factor has shifted from “writing code” to “specification and verification done by humans.” Agents can handle the heavy lifting of implementation, while human contributors focus on higher-leverage work: deciding what to build and ensuring it’s built right. Having the open-source community participate in managing Agents could, in theory, break through the manpower ceiling of an internal team.

The secondary reason is strategic positioning in a niche. Warp points out that there is currently no fully functional open-source Agentic Development Environment (ADE) on the market. By open-sourcing its client, Warp aims to become the benchmark alternative in this emerging field, differentiating against well-funded closed-source competitors.

It’s worth noting that Warp has had open-source plans since its initial release in 2022, but only executed them in 2026. The team explains that “the rise of Agents” changed the feasibility of open-source collaboration. Without Agent assistance, the review and integration costs of large-scale community contributions would be unbearable.

What Is the Agent-first Workflow

The Agent-first Workflow is the core collaboration model Warp adopted after going open source. It works like this: community contributors propose feature directions or submit requests, Warp’s Oz platform dispatches AI Agents to do the coding, planning, testing, and other implementation work, while the core team handles final quality control and merge decisions.

The difference from traditional open-source projects: in the traditional model, community PRs require manual review and testing by the core team, making manpower the bottleneck; in the Agent-first model, Agents take on most of the implementation and verification work, and the human contributor’s role shifts from “writing code” to “setting direction” and “doing verification.”

Warp uses public GitHub issues as the single source of truth for feature tracking and has published a public roadmap for the ADE. This means the community can directly influence product direction by filing issues and joining discussions.

What Open Source Brings to Users

Transparency and Auditability

The terminal is the developer’s core entry point for interacting with the system, and the commands and data it handles often involve sensitive information. Open source means users can directly audit what Warp executes locally and how data flows. This has real value in security and compliance scenarios, especially for enterprise environments that need to vet third-party tools.

Greater Customizability

Warp has also introduced a programmable settings file, supporting configuration portability across devices. Users can adjust the interface level to their preferences, from a minimal terminal to a full ADE interface with diff views and file trees.

More Model Choice

The open-source version adds support for open-source models such as Kimi, MiniMax, and Qwen, and introduces an “auto (open)” routing feature that automatically selects the best model based on task type, reducing the cost of manual switching.

Free vs. Paid: What’s the Difference

Warp’s business model is a hybrid of “open-source client + paid cloud services.” Core terminal features are free for all users, while AI capabilities and cloud resources are tiered and billed by usage.

Dimension	Free	Build ($18/month)
Core terminal features	Fully free	Fully free
Source code	Open source under AGPL; viewable/modifiable	Same open-source codebase
Monthly AI Credits	150 (first 2 months), then 60	1,500
Available AI models	Limited	Frontier models from OpenAI, Anthropic, Google
Concurrent cloud Agents	4	20
Cloud Agent compute	2 vCPU / 4 GiB	4 vCPU / 8 GiB
Codebase indexing	3 codebases, 3,000 files each	40 codebases, 100,000 files each
Warp Drive knowledge base	10 workflows + 3 notebooks	Unlimited
BYOK (bring your own API key)	Not supported	Supported

For pure terminal users, open source doesn’t change the experience. Warp’s block editing, autocomplete, history search, and other features remain free. The barrier to AI features is credits and model access.

In late 2025, Warp simplified its pricing from multiple tiers (Pro/Turbo/Lightspeed) into a single Build plan and introduced a Reload Credits mechanism: excess usage can be purchased at 50% less than the old pricing, valid for 12 months.

One option favorable to heavy users is BYOK (Bring Your Own Key): Build and above users can connect their own OpenAI, Anthropic, or Google API keys, so AI costs go directly onto their existing provider bills, with Warp charging only the $18/month base subscription. For developers who already have AI subscriptions, this can significantly cut total costs.

How Different Users Should Choose

User Type	Recommended Option	Expected Cost
Pure terminal users	Free tier	$0
Light AI users	Free tier credits	$0
Developers with existing AI API keys	Build + BYOK	$18/month
Teams needing collaboration	Business ($45/person/month)	Per-seat pricing
Enterprises with strict data sovereignty	Enterprise (custom)	Custom pricing

The free tier’s 60 credits per month is quite tight for any substantive AI-assisted development. This means most users who want Warp’s AI features will eventually need to go the paid or BYOK route.

Warp vs. Closed-Source Competitors

Warp’s open-source strategy sets it apart from closed-source competitors like Cursor and GitHub Copilot.

Dimension	Warp	Cursor / Copilot
Client code	Open source under AGPL	Closed source
Core revenue	Cloud Agent services + AI credits	Subscription fees
Model choice	Multiple providers, including open-source models	Mostly proprietary/partner models
Community involvement	Agent-first; community sets direction	Officially driven
Self-hosting options	Supported in Enterprise	Generally not supported

The strong copyleft nature of the AGPL license means any derivative work based on Warp’s code must also be open source. This may make some enterprises hesitate to deeply customize, but it also ensures community contributions flow back into the main project.

The Product’s Future Direction

Short Term: Competing on Iteration Speed

If the Agent-first collaboration model works, Warp’s feature iteration speed could significantly outpace closed-source competitors that depend on in-house engineers. Community contributors propose directions, Agents do the implementation, and the core team handles quality control. In theory, this pipeline can process a large number of feature requests in parallel.

Medium Term: Contesting the Open-Source ADE Niche

Warp explicitly positions itself as a pioneer of the “open-source Agentic Development Environment.” This niche is currently empty, but competition will intensify quickly. Whether Warp can build enough community scale and contribution quality will determine whether it can hold this position.

Long Term: Cloud Services as the Profit Core

Open-sourcing the client won’t shake Warp’s business model. AI compute, cloud Agent orchestration, and enterprise-grade management (SSO, data retention controls, self-hosted Agents) are the real revenue core. This resembles GitLab’s “open-source core + paid features” path. Warp’s Enterprise plan even supports Bring Your Own LLM and self-hosted cloud Agents, targeting large organizations with strict data sovereignty requirements.

Potential Risks and Uncertainties

The Agent-first collaboration model is experimental, and its effectiveness remains to be proven. Whether community contribution quality can be effectively amplified through Agents, and whether the core team’s review bottleneck will reappear in a new form, are open questions.

Additionally, the free tier’s low credit allowance may push many users toward paid plans. Warp needs to balance free-user growth against paid conversion, avoiding the free tier becoming a “trial trap” that harms the user experience.

Summary

Warp’s open sourcing is not the traditional “giving back to the community”; it is a business model experiment built on Agent capabilities. It uses an AGPL open-source client to build trust and transparency, and the Oz platform and cloud Agent services to build its commercial moat.

For users, pure terminal features are unaffected, and the cost of AI capabilities depends on usage intensity. For the industry, this marks a potential new phase of open-source collaboration where “humans set the direction, Agents do the execution.” Whether this model endures depends on Agent quality, community activity, and Warp’s ability to balance free and paid.

References

Warp Is Now Open-Source, Warp official blog, 2026-04-28
Warp Pricing, Warp official pricing page

Claude Cowork vs. Code Mode: The Key Differences

Wed, 29 Apr 2026 02:54:21 +0800

In early 2026, Anthropic introduced three parallel work modes to the Claude desktop client: Chat, Cowork, and Code. Chat continues the traditional conversational interaction, while Cowork and Code represent two different directions of Agentic capability expansion. Both share the same Claude model engine, yet differ fundamentally in interaction interface, toolchain, and optimization targets.

This article focuses on comparing Cowork and Code, systematically covering core positioning, capability boundaries, and real-world use cases.

1. Core positioning: the same engine, two different kits

Cowork and Code aren’t two independent products — they’re two packaging forms of the same intelligence engine aimed at different user groups.

Dimension	Cowork	Code
Design goal	General office automation for non-developers	Code engineering tool for developers
Interface form	GUI tab inside the Claude Desktop app	Terminal CLI / IDE plugin / Desktop Code tab
Underlying capabilities	Based on Computer Use (screenshots + mouse/keyboard control)	A full development toolchain based on MCP + Shell + Git
File access	Explicitly authorized folders, sandboxed access	Full project-level filesystem access
Code execution	Executes after showing a plan; visualization-oriented	Runs shell commands, tests, and builds directly
Git integration	None	Full lifecycle (branches, commits, PRs)

The relationship can be summarized as: same engine, different equipment. The model-level reasoning capabilities are identical (both use Opus or Sonnet); the differences lie in the tool set the model is allowed to call and how humans interact with it.

2. Cowork: the “desktop automation colleague” for non-technical users

Cowork launched in January 2026. Anthropic positions it as “Claude Code for the rest of your work” — extending the Agentic capabilities developers already enjoy to non-technical scenarios.

Core capabilities

Local file read/write: after the user authorizes specific folders, Cowork can directly read, create, and modify files without manual uploads and downloads
Cross-app desktop automation: built on Computer Use, it identifies UI elements via screenshots and controls mouse and keyboard, operating any desktop program — Excel, PowerPoint, browsers, and more
Browser automation: reads Gmail and backend web data, using the user’s already-logged-in sessions to complete web-level tasks
Subagent orchestration: breaks complex tasks into parallel workflows, automatically merging results from multiple subtasks
Scheduled tasks: supports the /schedule command to set up daily or weekly recurring automation flows
Professional document generation: directly outputs office formats such as PPTX, XLSX (including formulas), and DOCX

Typical use cases

File organization: “Sort the 200 screenshots on my desktop by date and generate an index table”
Data extraction: “Read 50 PDF invoices and extract supplier names, dates, and amounts into Excel”
Scheduled reports: “Every Monday at 9 AM, automatically summarize Salesforce sales data and generate a weekly report”
Presentations: “Generate a formatted PowerPoint deck based on the research materials”

Cowork’s design philosophy is lowering the barrier to entry: the user describes the goal in natural language, and the system executes autonomously after presenting an execution plan, with real-time progress visible in the GUI.

3. Code: the developer’s “terminal-level engineering assistant”

Code mode (and the earlier-released Claude Code CLI) targets software development, offering deep access to codebases and development toolchains.

Core capabilities

Codebase-level understanding: automatically maps project structure, dependency relationships, and cross-file references to build a complete code context
Multi-file refactoring: modifies code across files in a single session, updates import statements, adjusts test cases, and fixes build errors
Terminal command execution: runs shell scripts, test suites, build pipelines, and deployment commands directly
Full Git lifecycle: a complete loop from reading issues and writing code to running tests and submitting PRs
MCP tool connections: connects to external systems like GitHub, Slack, Jira, and databases via the Model Context Protocol
Background agents and /loop: supports long-running tasks such as reviewing PRs every 5 minutes or continuously monitoring deployment status (up to a week)
Plan mode: read-only exploration of the codebase without modifying any files, suitable for the understanding and analysis phase

Typical use cases

Feature development: “Add JWT authentication to the Express app, create middleware and routes, and write tests”
Code refactoring: “Refactor the service module across 8 files, run the tests, and submit a PR”
Bug hunting: “Track down the frontend rendering issue, open the browser debugger, and analyze the UI with screenshots”
Continuous monitoring: “Set up a background agent to continuously monitor new PRs in the repo and automatically perform code reviews”

Code’s design philosophy is precise control: developers interact with the model via terminal or IDE, can review every intermediate output, and make fine-grained corrections when necessary.

4. Underlying technical differences

Computer Use vs. MCP + Shell

Cowork’s core technology stack is Computer Use — Claude captures screen images, identifies UI elements, and then simulates mouse clicks and keyboard input to complete tasks. The advantage is generality: in theory, it can operate any application with a graphical interface. The cost is lower efficiency — every step requires screenshots, analysis, and simulated input, with limited tolerance for UI changes.

Code’s core technology stack is MCP (Model Context Protocol) + Shell commands. MCP gives the model a structured tool-calling interface (reading files, executing commands, querying databases), while Shell grants direct access to system-level tools. The advantage is precision and efficiency: the model can manipulate the filesystem directly, run compilers, and invoke test frameworks without the indirect simulation of a GUI layer.

Memory mechanisms

Cowork: persistent memory based on Projects, retaining task history and connector configurations across sessions
Code: project-level instructions based on CLAUDE.md files plus automatic memory; finer-grained memory, deeply tied to codebase structure

5. Choosing between them

The following decision table helps you quickly determine which mode to use:

Task characteristics	Recommended mode
Involves codebases, version control, testing, and builds	Code
Requires operating multiple office apps, organizing files, generating documents	Cowork
Repetitive office tasks that need scheduled execution	Cowork
Needs deep code understanding and cross-file refactoring	Code
Quick Q&A, brainstorming, mobile interaction	Chat

Common misconceptions

Cowork is not a GUI version of Code: the two have completely different interfaces and optimization directions; Cowork lacks Git support, terminal access, and IDE integration
Writing code in Cowork is inefficient: without codebase-level context and build toolchains, cross-file refactoring is limited
Configuring Code for non-developers is a poor fit: the terminal interface and development workflow impose unnecessary learning costs on operations, sales, HR, and similar roles

6. Summary

Cowork and Code represent Anthropic’s two productization paths for Agentic AI: Cowork centers on generality and ease of use, targeting daily office automation for knowledge workers; Code centers on precision and control, targeting engineering needs of software developers. The two aren’t in competition — they’re complementary. The same user may need both in different scenarios.

From a broader perspective, the three-layer structure of Chat, Cowork, and Code also reflects an evolution trend in AI products: from passive response (Chat) to proactive execution (Cowork/Code), from single conversation to tool integration and then to system-level automation. For users, understanding each mode’s boundaries and strengths is a prerequisite for using the Claude ecosystem effectively.

References

This article synthesizes information from the following public sources:

Web-Based Presentations: Several Open-Source Options More Flexible Than Traditional Slides

Tue, 28 Apr 2026 02:03:53 +0800

Using the web for presentations was once a niche choice among technical practitioners. But over the past two years, more and more non-technical users have been trying it — in academic presentations, product launches, corporate training, and similar scenarios, web-based slides are moving from the fringe to the mainstream. The driving force behind this isn’t complicated: web technologies are naturally cross-platform, version-control friendly, and offer interactivity that traditional PPT cannot easily achieve.

This article reviews several web presentation tools worth attention, split into two layers — core frameworks and AI generation — with directly accessible project links.

1. The Core Framework Layer

The infrastructure of web presentations is built on a set of open-source frameworks. They liberate slides from proprietary formats and rebuild them on open web technologies.

reveal.js: The “De Facto Standard” for HTML Presentations

reveal.js is currently the most mature HTML presentation framework, developed by Hakim El Hattab. Its core positioning: anything that can be done on a web page can be used in a presentation.

The framework supports vertically nested slides, speaker view (with timer and next-slide preview), Auto-Animate, LaTeX formula rendering, and more. Slide transitions include fade, slide, convex, concave, zoom, and other modes. For those unfamiliar with code, the same author also provides a companion no-code editor, slides.com.

reveal.js suits technical presentations with high requirements for interactive effects — for example, embedding live code execution, iframe web content, or complex CSS animations.

Project link: github.com/hakimel/reveal.js

Slidev: The Developer’s Markdown Choice

Slidev is designed specifically for developers. Its tech stack is built on Vite + Vue 3 + UnoCSS, using Markdown as the content source format. Its biggest advantage is unifying the “writing code” and “making slides” workflows in the same environment.

Slidev’s standout features include Shiki-powered code highlighting, built-in live code demos, Mermaid diagram support, KaTeX math formulas, presenter pen annotations, and a built-in recording tool. For deployment, running slidev build outputs a static site that can be hosted on any platform.

For developers who already manage documents with Git, Slidev’s Markdown source files are naturally version-controlled — an advantage traditional PPT can’t match.

Project link: github.com/slidevjs/slidev

Marp: The Lightest Markdown Option

Marp stands for Markdown Presentation Ecosystem and offers an out-of-the-box experience as a VS Code extension. After installing the extension, create a new Markdown file, add the marp: true front-matter config, and you’re ready to make slides.

Marp has the lowest learning curve of the three, and supports exporting to PDF, PPTX, and HTML. It suits quick academic reports, work briefings, and other scenarios that don’t demand high design complexity.

Project link: github.com/marp-team/marp

Spectacle: A Presentation Option for the React Ecosystem

Spectacle is a React component-based presentation framework maintained by Nearform (formerly FormidableLabs), with slides written in JSX. It integrates seamlessly with the React ecosystem and supports live coding. For teams already deeply invested in the React stack, Spectacle enables component reuse — for example, embedding elements from your UI component library directly into a deck.

Project link: github.com/FormidableLabs/spectacle

2. The AI Generation Layer

Frameworks solve the “how to present” problem; AI tools are starting to solve “how to generate content.” Here are the open-source options worth watching.

Presenton: The Most Feature-Complete AI Presentation Generator

Presenton has 4.8k stars on GitHub and is open sourced under the Apache 2.0 license. It positions itself as an open-source alternative to Gamma, Beautiful.ai, and Decktopus.

The project’s core features include:

BYOK model support: Use APIs from OpenAI, Gemini, or Anthropic, or connect local models via Ollama
Template inheritance: Upload existing PPTX files to use as design templates
Fully local operation: Offers both an Electron desktop app and Docker self-hosting; all processing can be done locally
Built-in MCP Server: Supports the Model Context Protocol for integration with other AI toolchains

Deployment is very simple — a single Docker command starts the service. For data-privacy-sensitive scenarios, such as internal corporate reporting or presentations involving trade secrets, Presenton’s local operation capability is an important plus.

Project link: github.com/presenton/presenton

PPTAgent: An Academic-Grade Generation Option

PPTAgent is a research project published at EMNLP 2025, developed by the Institute of Computing Technology, Chinese Academy of Sciences (ICIP-CAS). Its distinguishing feature is a systematic quality evaluation mechanism. The project uses a two-step generation pipeline and includes the PPTEval scoring system, which quantitatively evaluates generated results across three dimensions: design, flow, and content quality.

PPTAgent also supports Docker deployment in seconds. It suits research or enterprise environments that need quantifiable evaluation of generation quality — for example, when you need to prove to clients that AI-generated content meets a specific quality bar.

Project link: github.com/icip-cas/PPTAgent

3. The Toolchain Layer: Format Conversion

Dedicated conversion tools bridge web presentations and traditional workflows.

DeckTape: High-Quality PDF Export for HTML Presentations

DeckTape is built on Puppeteer and the Chrome rendering engine, and can export 13+ HTML presentation frameworks — including reveal.js, Slidev, impress.js, and remark — to high-quality PDF. Its usage is simple:

The tool also supports selective export (e.g., only pages 1, 3, and 5-10), multi-resolution screenshot capture, and Docker containerized operation. For offline distribution or print backup scenarios, DeckTape is an indispensable part of the web presentation workflow.

Project link: github.com/astefanutti/decktape

4. Selection Advice

Need / Scenario	Recommended Option
Already have Markdown content; want a web presentation quickly	Slidev or Marp
Need AI assistance to generate a complete deck from scratch	Presenton (self-hosted)
Want complex interactive effects and embedded web apps	reveal.js
React stack; need componentized reuse	Spectacle
Need PDF backups or offline distribution	Any framework + DeckTape
Data-sensitive; must run locally	Presenton + local Ollama models

5. A Workflow Worth Watching

These tools are currently forming a clear pipeline:

Markdown/text → AI-generated content → web presentation framework rendering → DeckTape PDF export

This means users can generate an outline with AI, refine it in Markdown with Slidev or Marp, build it into an interactive web presentation, and export a PDF with DeckTape as a fallback. This “web-first, PDF as backup” pattern is the technical foundation behind the claim that “web presentations are better.”

Web presentations have objective advantages in interactivity, version control, and cross-platform consistency. But they’re not a silver bullet: traditional PPT still holds ground in business compatibility, review/annotation features, and acceptance among non-technical users — real constraints web solutions must face. Which tool you choose ultimately depends on your specific use case and audience.

Guide to Buying China's Mainstream AI Coding Plans: A Hands-on Speed and Price Comparison of 9 Platforms

Thu, 16 Apr 2026 09:46:38 +0800

Since the second half of 2025, Chinese LLM vendors have been rolling out Coding Plan subscriptions aimed at developers, replacing the traditional per-token billing with a fixed monthly fee and significantly lowering the barrier to AI-assisted programming. However, the platforms differ widely in pricing, quotas, response speed, and model support—and some even have hidden clauses like different metering units and strict limits, leaving many developers struggling to choose.

This article combines a hands-on Xiaohongshu test note, an in-depth cross-review from Cnblogs (博客园), and each platform’s official documentation to sort through 9 Chinese Coding Plans from the two core dimensions of price and speed, hoping to inform your purchasing decision.

1. Coding Plan billing models and pitfalls to avoid

Before comparing specific plans, it’s necessary to clarify the different metering units these vendors use, as this is the easiest place to trip up:

API request count: Alibaba Cloud Bailian (百炼), Volcengine Ark (火山方舟), and Infinity (无问芯穹) use this. One user prompt can trigger 5–30 model calls in the backend, and each call counts as 1 API request (per Tencent Cloud’s official docs).
Prompt count: Zhipu GLM and MiniMax use this. 1 Prompt is roughly equivalent to 1,200–1,600 API requests.
Token metering: Kimi switched to this mode on January 28 of this year, billing by input/output tokens, and cache hit rate directly affects actual usable quota.

Because the metering units differ, comparing raw numbers is meaningless. For example, Bailian Lite’s “1,200 API requests every 5 hours” and Zhipu Lite’s “80 Prompts every 5 hours” may amount to similar real-world usage intensity.

2. Price and quota comparison

2.1 The big four platforms

According to the screenshots in the Xiaohongshu note and the Cnblogs compilation, the pricing strategies of Alibaba Cloud Bailian, Volcengine Ark, Tencent Cloud, and JD JoyCoder are highly convergent:

Platform	Lite Plan	Pro Plan	Core quota (Lite)	Supported models
Alibaba Cloud Bailian	¥40 (first month ¥7.9)	¥200	1,200/5h, 9,000/week, 18,000/month	Qwen3.5-Plus, Qwen3-Coder-Next, GLM-4.7, Kimi-K2.5
Volcengine Ark	¥40 (first month ¥8.91)	¥200	Same as Bailian	Doubao-Seed-Code, DeepSeek-V3.2, GLM-4.7, Kimi-K2.5
Tencent Cloud	¥40 (first month ¥7.9)	¥200	Same as Bailian	Hunyuan series, MiniMax-M2.5, Kimi-K2.5, GLM-5
JD JoyCoder	¥40	¥200	Same as Bailian	DeepSeek-V3.2, Kimi-K2.5, MiniMax-M2.7, GLM-5

2.2 Emerging AI vendors

Compared to the big four, emerging vendors’ pricing is more scattered:

Platform	Entry price	Core quota	Billing	Highlights
Infinity	¥19.9/month	1,000/5h, 6,000/week	API requests	Lowest monthly fee, multi-model aggregation
MiniMax	¥29 (first month ¥9.9)	40 Prompt/5h, no weekly cap	Prompt	Lowest entry price, no weekly limit
Kimi	¥49 (Andante)	Per token (3x for a limited time)	Token	Native multimodal, 256K long context
Zhipu GLM	¥49 (after the 2-month price increase)	80 Prompt/5h, 400/week	Prompt	Pure in-house models, 20+ tool integrations
StepFun	Not tested	—	—	No hands-on data yet

From a value-for-money standpoint:

Budget-conscious users: Infinity (¥19.9) and MiniMax (¥29) have lower entry barriers.
New users trying the waters: Alibaba Cloud Bailian’s first-month ¥7.9 is currently the lowest known trial price.

3. Hands-on speed tests: TTFT and TPS

The following speed data comes from a Xiaohongshu hands-on test note, tested under the conditions of “daytime @ 10K tokens,” measuring time to first token (TTFT) and TPS generation speed respectively. This data directly reflects the “responsiveness” of coding and code-generation efficiency.

3.1 Time to first token (TTFT)

Platform	Fastest model	TTFT	Slowest model	TTFT
Zhipu GLM	glm-5-turbo	1.43s	glm-5	7.82s
Tencent	hunyuan-2.0-thinking	2.51s	kimi-k2.5	12.38s
MiniMax	m2.1	2.44s	m2.5	5.54s
Alibaba	glm-4.7	2.76s	qwen3-coder-next	11.58s
Infinity	deepseek-v3.2-thinking	3.26s	kimi-k2.5	7.76s
Volcengine	doubao-seed-2.0-pro	3.29s	glm-4.7	21.52s
JD	deepseek-v3.2	~5s	kimi-k2.5	~19s
Kimi	kimi-for-coding	5.71s	—	—

Observations: Zhipu GLM’s glm-5-turbo is the fastest of all at 1.43s TTFT; the time-to-first-token for some models on Volcengine and JD is notably higher, hitting 21.52s and 19s respectively, possibly related to platform scheduling policies or model deployment methods.

3.2 TPS generation speed

Platform	Fastest model	TPS	Slowest model	TPS
Zhipu GLM	glm-4.5-air	103	glm-5	23
Volcengine	doubao-seed-2.0-pro	76	kimi-k2.5	23
Tencent	hunyuan-2.0-thinking	76	glm-5	30
Alibaba	qwen3-coder-next	67	glm-4.7	41
Infinity	minimax-m2.5	51	kimi-k2.5	25
MiniMax	m2.5	48	m2.1	45
JD	deepseek-v3.2	35	glm-5	25
Kimi	kimi-for-coding	35	—	—

Observations: Zhipu’s glm-4.5-air reaches 103 TPS, significantly ahead of other platforms; Volcengine and Tencent’s Hunyuan/Doubao models also hit 76 TPS. JD and Kimi are relatively slow at around 35 TPS.

In addition, MiniMax officially claims its M2.5 model can reach 100+ TPS, which differs from the 48 TPS measured on the MiniMax platform in the Xiaohongshu note, indicating that the same model may perform differently when deployed on different platforms.

4. Platform reviews and buying recommendations

Combining price, quota, and speed data, here are recommendations for different usage scenarios:

New users / those wanting to try it cheap

First choice: Alibaba Cloud Bailian Lite (first month ¥7.9). Rich model selection, backed by Alibaba Cloud infrastructure, with solid stability. Downsides: only the primary account is supported, and the config documentation isn’t beginner-friendly.

Budget-conscious, light use (monthly budget ≤ ¥30)

First choice: Infinity Lite (¥19.9/month). Quota close to Bailian’s at half the price, ideal for light developers who code 2–3 times a week.
Second choice: MiniMax Starter (¥29/month). No weekly cap; quota only refreshes every 5 hours, good for continuous use.

Daily development, moderate use (monthly budget ¥40–50)

First choice: Alibaba Cloud Bailian Lite (regular ¥40) or Volcengine Ark Lite (regular ¥40). Both have transparent quotas and many model choices.
Not recommended: Zhipu GLM (¥49 after the price increase, worse value) and Kimi (¥49, few tool integrations and quota heavily affected by cache).

Heavy development, full-stack, or multi-model switching

First choice: Alibaba Cloud Bailian Pro or Volcengine Ark Pro (¥200/month). Around 5x the quota of Lite, with free switching between multiple models. Volcengine also supports Auto smart scheduling.
If you prefer GLM’s in-house models, consider Zhipu GLM, but note its weekly limit and peak-time quota multipliers (3x during peak, 2x off-peak).

Pursuing ultimate response speed

If time-to-first-token and generation speed are your top priorities, Zhipu GLM’s glm-5-turbo (1.43s TTFT) and glm-4.5-air (103 TPS) perform best.

5. Summary

The Chinese Coding Plan market is iterating rapidly, with price wars and model wars running in parallel. When choosing, don’t fixate on surface prices; instead, focus on three core questions:

What is the metering unit? API requests, Prompt counts, or tokens? Different units can’t be compared directly.
How does the quota mechanism work? Refreshed every 5 hours, capped weekly, or capped monthly? This determines whether you can sustain high-intensity use.
Is the speed responsive? TTFT and TPS directly affect the coding experience, and the same model can perform wildly differently across platforms.

A final reminder: plan policies change frequently across vendors (e.g., Zhipu’s price increase, Kimi switching to token billing, Alibaba Cloud discontinuing its Lite tier), so be sure to confirm the latest details on each platform’s official website before subscribing.

Data 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.

How We Turned Ghost Publishing into an OpenClaw Skill

Thu, 02 Apr 2026 11:56:02 +0800

This post documents a concrete implementation: getting OpenClaw to reliably create, update, and publish Ghost posts. The goal was simple: the process must be reusable, the configuration must stay contained, and when something goes wrong we need to know exactly which step failed.

Goal

We wanted OpenClaw to do three things:

Understand Ghost’s publishing pipeline
Turn the publishing flow into a reusable skill
Handle authentication and publishing through local environment variables, without writing secrets into code

Which Docs We Consulted First

We didn’t start with sample articles but with the parts of the Ghost official docs covering APIs and authentication, focusing on two questions:

Which APIs are read-only
Which APIs can create and update content

After reading, the conclusion was clear: the Content API is fine for reading, but actual writes go through the Admin API.

What This Skill Does

We organized the flow into ghost-publisher.

Its responsibility is narrow and well-defined:

Accept publishing fields such as title, body, slug, and tags
Handle Markdown or HTML input
Normalize the content structure before publishing
Call the Ghost Admin API to create or update posts
Return verifiable results, such as post id, slug, URL, and status

The benefit is that OpenClaw no longer needs to reinterpret Ghost’s rules every time — it can just route through this skill directly.

Which Environment Variables You Need

Conceptually only two pieces of configuration are required:

The Ghost site address
The Ghost Admin API key

Both values should live in a .env file, read by OpenClaw at startup. Don’t write them into posts, logs, or prompts.

Why It Failed the First Time

Initially we grabbed the common Content API key from a Ghost Integration. It can read content but cannot write it.

That was the root cause of the first failure:

The Content API key is read-only
To write posts, you must use an Admin API key
An Admin API key is only available after creating a Custom Integration in the Ghost admin panel

Until the permission model was straightened out, the flow seemed correct but could never actually publish.

Why You Need to Restart OpenClaw After Editing `.env`

Because OpenClaw reads environment variables at startup.

So after editing .env, you must restart OpenClaw for the new host and key to take effect. Editing the file alone won’t do — the process still holds the old configuration.

The Formatting Issues We Actually Ran Into

We also confirmed a few publishing constraints this time, which we can carry forward into future articles:

Don’t repeat the top-level title in the body, since Ghost already has a title field
Normalize the Markdown before publishing to avoid messy blank lines, indentation, and repeated list markers
Keep slugs clear and consistent with the topic; English is usually more intuitive than forcing Chinese characters

If these issues are not addressed, pages look messy and the content feels thrown together.

How to Safely Let AI Handle an Environment Containing Secrets

If AI is involved in this kind of work, the boundaries need to be spelled out first:

Use only the designated environment variables
Don’t output the full .env contents
Don’t echo the value of any key
Only return non-sensitive verification results

In other words, the AI can tell you “whether the config is active,” “whether a post is published,” and “what slug was returned,” but it must not leak any secret values.

Result

Once this flow was working, OpenClaw can now reliably:

Read the local configuration
Process posts through ghost-publisher
Write to Ghost via the Admin API
Return verifiable publishing results

If we later need to extend this to updating posts, batch publishing, or more complex content formats, the foundation is already in place — we can simply reuse this pipeline.