DEV Community: Gabriel Wu

Custom Tailscale DERP Server

Gabriel Wu — Mon, 02 Mar 2026 03:19:02 +0000

Deploying a Custom Tailscale DERP Server with DNS-01 SSL (When Ports 80/443 are Blocked)

Setting up a self-hosted Tailscale DERP (Designated Encrypted Relay for Packets) node is the best way to ensure low-latency, private connections. But if your VPS provider or local ISP blocks ports 80 and 443, the built-in Let’s Encrypt automation will fail, leaving you in a “no viable challenge type found” loop.

Here is the battle-tested, three-tier configuration to get your DERP node running on a custom port (e.g., 3443) with a valid SSL certificate.

Phase 1: Cloudflare Side (The DNS Validator)

Since we can’t use HTTP-01 challenges (because port 80 is blocked), we use DNS-01. This proves you own the domain by adding a temporary TXT record via API.

Create an API Token:
- Go to My Profile > API Tokens > Create Token.
- Use the Edit zone DNS template.
- Set Zone Resources to your specific domain (e.g., example.com).
Copy the Token: You will only see this once.
DNS Record: Ensure you have an A record pointing your subdomain (e.g., derp.example.com) to your VPS IP.

Phase 2: VPS Side (The Engine Room)

We will use Docker for the DERP server and a Python virtual environment for Certbot and its Cloudflare DNS plugin, avoiding conflicts with system packages.

1. Prepare the Virtual Environment

Install the necessary Python headers and create a dedicated space for Certbot:

# Install dependencies
sudo apt update
sudo apt install python3-venv python3-pip -y

# Create the venv in /opt/certbot
sudo python3 -m venv /opt/certbot/
sudo /opt/certbot/bin/pip install --upgrade pip

2. Install Certbot & Cloudflare Plugin

Install the packages into the virtual environment and symlink the binary so you can run certbot from anywhere:

sudo /opt/certbot/bin/pip install certbot certbot-dns-cloudflare

# Create a symlink for ease of use (use -f to overwrite if exists)
sudo ln -sf /opt/certbot/bin/certbot /usr/bin/certbot

3. Configure Credentials

Create a secure directory for your Cloudflare API token (in root’s home, since certbot runs as root):

sudo mkdir -p /root/.secrets/
sudo nano /root/.secrets/cloudflare.ini

Inside cloudflare.ini, add:

dns_cloudflare_api_token = YOUR_CLOUDFLARE_TOKEN_HERE

Security check: Run sudo chmod 400 /root/.secrets/cloudflare.ini to restrict access.

4. Request the Certificate (DNS-01 Challenge)

Trigger the challenge. Certbot will create a temporary TXT record via Cloudflare, verify it, and pull your certs—no port 80 required:

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
  --dns-cloudflare-propagation-seconds 60 \
  -d derp.example.com \
  --agree-tos \
  --register-unsafely-without-email

Optional: Add --email your@example.com if you want Let’s Encrypt expiry notices.

5. Copy Certs and Deploy the Container

The container reads certs from /app/certs. Certbot stores them under /etc/letsencrypt/live/. Copy (or symlink) them into /root/derper-data with the names the image expects, then start the container. One-time setup:

SOURCE="/etc/letsencrypt/live/derp.example.com"
DEST="/root/derper-data"
mkdir -p ${DEST}
cp ${SOURCE}/fullchain.pem ${DEST}/derp.example.com.crt
cp ${SOURCE}/privkey.pem ${DEST}/derp.example.com.key
chmod 644 ${DEST}/derp.example.com.crt
chmod 600 ${DEST}/derp.example.com.key

6. Start the Container

Since we use manual mode, mount the certificate directory to the path fredliang/derper expects: /app/certs.

docker run -d \
  --name derper \
  --restart always \
  --net=host \
  -v /root/derper-data:/app/certs \
  -v /root/derper-data:/var/lib/derper \
  -e DERP_DOMAIN=derp.example.com \
  -e DERP_ADDR=:3443 \
  -e DERP_CERT_MODE=manual \
  -e DERP_HTTP_PORT=-1 \
  -e DERP_VERIFY_CLIENTS=false \
  fredliang/derper:latest

Note: DERP_VERIFY_CLIENTS=false lets anyone use your DERP server. To restrict access to your Tailnet members, set to true and add the tailscaled socket mount:

  -v /var/run/tailscale:/var/run/tailscale:ro \
  -e DERP_VERIFY_CLIENTS=true \

Important: This requires tailscaled running on the host AND the Docker image’s derper version must match the host’s tailscaled version. Version mismatches cause verification failures. For simplicity, most self-hosted setups use false since TLS still encrypts all traffic and DERP only relays already-encrypted WireGuard packets.

Phase 3: Tailscale Side (The Controller)

Now that the server is humming on port 3443, we need to tell the Tailscale network how to find it.

Log into your Tailscale Admin Console.
Edit your ACL JSON to include the derpMap.

Crucial: You must specify the DERPPort as 3443. With OmitDefaultRegions: true, your custom DERP is the only option—if it fails, clients have no relay fallback. With OmitDefaultRegions: false, Tailscale may prefer default DERP regions over your custom node (due to latency heuristics or reachability issues), potentially causing unexpected routing. Test with tailscale netcheck after setup to confirm your node is selected.

"derpMap": {
    "OmitDefaultRegions": true,
    "Regions": {
        "901": {
            "RegionID": 901,
            "RegionCode": "My-Custom-Node",
            "Nodes": [
                {
                    "Name": "1",
                    "RegionID": 901,
                    "HostName": "derp.example.com",
                    "DERPPort": 3443,
                    "IPv4": "YOUR_VPS_IP",
                    "InsecureForTests": false
                }
            ]
        }
    }
}

Phase 4: Verification – The “200 OK” Moment

Before you celebrate, run this from your local machine (Mac/Linux/Windows). Replace derp.example.com with your hostname if different:

curl -Iv https://derp.example.com:3443

Success: You see HTTP/1.1 200 OK and SSL certificate verify ok.
Failure: If it hangs on Client Hello, your VPS firewall (iptables) is blocking port 3443, or the Docker container cannot read the certificate files.

Finally, run tailscale netcheck on your local device. When you see your custom Region ID with a low latency number, you are officially off the grid!

Phase 5: Automation – Renewal and Deploy Hook

With the venv-based Certbot, use an explicit deploy hook for renewal. Create /root/update_derp_cert.sh, make it executable (chmod +x /root/update_derp_cert.sh), then use:

#!/bin/bash
# Path to your Let's Encrypt live directory
SOURCE="/etc/letsencrypt/live/derp.example.com"
DEST="/root/derper-data"

# Copy and rename for the container
cp ${SOURCE}/fullchain.pem ${DEST}/derp.example.com.crt
cp ${SOURCE}/privkey.pem ${DEST}/derp.example.com.key

# Ensure permissions are correct
chmod 644 ${DEST}/derp.example.com.crt
chmod 600 ${DEST}/derp.example.com.key

# Restart container to pick up new certs
docker restart derper

Then add a crontab entry via crontab -e to check for renewal daily:

# Check for renewal daily at 3 AM
0 3 * * * /usr/bin/certbot renew --quiet --deploy-hook /root/update_derp_cert.sh

Your DERP node is now a set-it-and-forget-it powerhouse.

Stop Using p7zip: Why You Should Switch to 7zz on Linux

Gabriel Wu — Sat, 28 Feb 2026 03:16:56 +0000

Stop Using p7zip: Why You Should Switch to 7zz on Linux

Still using p7zip on Linux? You’re working with software that hasn’t seen a significant update since 2016. While this community port served us well for years, the official 7-Zip for Linux has arrived—and it’s a game-changer.

The Problem: Stuck in 2016

Many package managers still default to p7zip version 16.02. This creates real problems:

No Modern Instruction Sets: The aging codebase can’t leverage AES-NI, AVX2, or AVX-512—features your CPU has had for years.
Compatibility Gaps: Archives created with newer compression methods? Good luck opening them.

The Solution: Meet 7zz

The official 7-Zip releases now include a standalone binary called 7zz. Everything is baked into one executable—no external dependencies, no path headaches.

Why It’s Faster

Switching from p7zip to 7zz delivers substantial performance gains on modern hardware:

Hardware Acceleration — Encryption and data operations now run at the silicon level using AES-NI and SIMD instructions.
Superior Multithreading — High-core-count CPUs finally get fully utilized.
Refined Algorithms — Years of micro-optimizations to LZMA/LZMA2 dictionary searches add up to real-world speed improvements.

How to Switch

If you’re using Pixi or Conda, install the modern 7zip package instead of p7zip. Then, use the standalone command:

# Avoid the legacy version
7z x archive.zip

# Use the modern standalone binary
7zz x archive.zip

Pro Tip: Keep Your Muscle Memory

Add an alias to your .bashrc or .zshrc, and keep typing 7z like you always have:

alias 7z='7zz'

See the Difference Yourself

Run the built-in benchmark to measure compression and decompression speeds on your hardware:

7zz b

Compare the results with your old p7zip installation. The numbers speak for themselves.

CLI is ALL you need

Gabriel Wu — Wed, 25 Feb 2026 23:56:41 +0000

CLI is ALL you need

Starting from Obsidian CLI

Not long ago, the veteran knowledge management software Obsidian officially announced its command-line tool Obsidian CLI, which is now available in the v1.12 preview release. Obsidian CLI provides functionality completely equivalent to the Obsidian GUI version: from basic note retrieval, editing, and task management, to advanced developer features such as plugin management, screenshots, JS code execution, Chrome DevTools Protocol (CDP), console message handling, and DOM element retrieval, all are supported in Obsidian CLI.

Some common Obsidian CLI commands are as follows:

# Open daily note
obsidian daily

# Add task to daily note
obsidian daily:append content="- [ ] Buy groceries"

# Search notes
obsidian search query="meeting notes"

# List daily tasks
obsidian tasks daily

# Create new note from template
obsidian create name="Trip to Paris" template=Travel

# List all tags with counts
obsidian tags counts

# Take screenshot
obsidian dev:screenshot path=screenshot.png

# Execute JavaScript code
obsidian eval code="app.vault.getFiles().length"

Why Now?

Obsidian has a massive plugin and theme ecosystem, but for a long time did not release an official CLI tool. Three years ago, the community created notesmd-cli (originally named obsidian-cli, renamed after the official CLI was released), a command-line tool that can operate on the Obsidian database without opening the Obsidian application.

From the notesmd-cli Star trend chart, we can clearly see that the project’s Star growth had been relatively stable since its inception, but after entering 2026, the project’s Star count experienced explosive growth.

The driving force behind this growth is obvious: the viral popularity of OpenClaw🦞. This lobster sparked the biggest wave in the AI community since 2026. As one of the default configured tools for OpenClaw, notesmd-cli naturally rode the wave of OpenClaw’s success.

Obsidian’s official release of CLI at this time undoubtedly indicates they saw the immense potential behind the notesmd-cli project. Obsidian’s knowledge management and task tracking system perfectly fits the needs of AI assistants like OpenClaw. Compared to simple MEMORY.md and memory/ folders, using Obsidian as an AI assistant’s memory bank is definitely a leap forward in productivity tools. The extensibility provided by over 2,000 plugins in the Obsidian community offers even more possibilities on top of this foundation.

Why CLI?

So, why CLI?

Because CLI is the natural language of AI Agents. Current mainstream LLMs all have complete tool-calling capabilities, and command-line invocation is one of the most fundamental and important tools for LLMs. When an AI Agent has command-line calling capabilities, it has the power to do anything:

Use cat to read files
Use grep to search for keywords
Use sed to modify files
Use curl to access web pages or call APIs
Use git to manage code
Use ssh for remote access
……

In fact, this is how humans used computers in the early days. No complex graphical interfaces needed, no fancy interaction methods required - a terminal and a keyboard could make a programmer feel like the world was in their hands.

Similarly, when an OpenClaw bot gains access to hundreds of CLI tools, it truly transforms from a chatbot into an omnipotent AI assistant.

Admittedly, current multimodal LLMs already possess powerful image and video understanding capabilities, and can use these abilities to control browsers and other desktop programs. However, this Computer Use approach consumes more tokens and also has greater uncertainty. The correctness of operations cannot be guaranteed; and correctly obtaining operation results is equally difficult (requiring another screenshot and parsing). In contrast, command-line invocation doesn’t rely on the LLM’s multimodal capabilities at all - text input, text output, everything seems incredibly natural.

Why Not MCP?

The Model Context Protocol (MCP) is a protocol proposed by Anthropic in November 2024, aimed at providing a standardized way for LLMs to call external tools. Through MCP, LLMs can call external tools without needing to know the specific implementation details of the tools.

MCP is good, but MCP also has quite a few problems, compared with CLI:

MCP is a feature specifically for Agents, with no direct use value for human users. A large number of existing software need specialized packaging to enter the MCP ecosystem. CLI, on the other hand, was born with computer systems and is the most fundamental way humans interact with computers.
MCP descriptions directly occupy Context. If hundreds of MCPs are enabled simultaneously, it means consuming tens of thousands of tokens during the system prompt phase, which directly increases API call costs and slows down response times. Moreover, these MCPs are not always useful for the current task, and conflicts may exist between MCPs, all of which can affect Agent execution precision. Some advanced users perform fine-grained control over MCPs used for each project, but this also brings additional workload and mental burden. In contrast, CLI provides self-explanatory documentation through the --help option, requiring far fewer fixed tokens than MCP.
There is currently no convenient mechanism for re-inserting MCP descriptions (writing as skills is a possible solution), which leads to imprecise Agent calls to MCP after Context grows. CLI-related information, on the other hand, can be inserted at the end of the current conversation at any time (for example, simply saying “please use the xxx command”), ensuring the Agent always has relevant information.

Let’s think again, what can MCP do that CLI cannot?

The answer is clear: everything that can be done through MCP can also be done through CLI. Because MCP and CLI are essentially just two different user interfaces.

CLI naturally possesses an important feature that MCP lacks: CLI invocations are essentially running Shell scripts, so they can easily form chained or decision-tree processes to achieve complex processing; whereas MCP currently can only make single calls to get single results. To achieve condition-based flow control, it must rely on the LLM’s autonomous design, and the process requires multiple MCP calls, increasing complexity and uncertainty.

CLI Design in the Agent Era

But why has MCP received more attention than CLI in the AI era? On one hand, it’s human instinct to chase the new: MCP is a new product of the AI era, while CLI is an “antique” that has existed for decades; on the other hand, it’s because CLI has long lacked a rigorous specification system. What we have are just scattered conventions:

Single-character short commands like -x
Long commands like --execute
Help options like -h|--help
Space-separated arguments
……

Compared to MCP’s strict specifications, CLI’s freedom and looseness has become an obstacle preventing its widespread use by Agents.

The key issue is not that CLI itself is inferior to MCP, but that traditional CLI design must change in the Agent era. Here I propose three core principles for CLI design in the Agent era:

Clear and Reasonable Hierarchical Structure

A good CLI tool’s help information should be a clearly structured, well-organized document. We know that the core of current Agent applications lies in context engineering. Reasonable hierarchical design can help Agents load the tool context needed for the current task on-demand after a few --help calls, thereby achieving better Context utilization efficiency.

Intuitive Command Style

Use the same verbs for the same type of resources;
Follow the same parameter order for the same type of verbs;
Maintain consistent semantics for global options (such as --verbose, --dry-run, --output, etc.);
Option naming should follow conventions as much as possible, don’t invent new vocabulary.

By following these principles, Agents can execute command calls with high accuracy without viewing help documentation (thus saving Context).

A simple design approach: think about how you would describe this command in natural language (English)? A command system that closely aligns with natural language can naturally enable Agents to achieve “what they think is what they see, what they see is what they get.”

Stable and Readable Structured Output

In the Agent era, CLI tools are oriented toward AI Agents instead of humans, so their output must also follow Agent-oriented design principles and must have a stable structure:

Can be formats like --json, --yaml, or in some cases, a stable text structure format (such as compilers, etc.);
Have clear exit codes and parsable error fields.

Structured output allows Agents to easily perform information extraction (with tools like jq) and process orchestration, thus fully leveraging the powerful capabilities of CLI.

Besides these three core principles, there are some details worth noting:

Write operations should support idempotency or --dry-run options as much as possible, so Agents can preview and debug;
For multi-agent and subagent architectures, CLI concurrency control needs to be considered. A simple file lock can avoid many write conflict issues.
Complex features should ideally have observability, so Agents can better troubleshoot when problems occur during calls.

Conclusion

The release of Obsidian’s official CLI tool is an important signal in the wave of AI assistants sparked by OpenClaw. When the MCP hype gradually settles down and we look back, the CLI that has accompanied us for decades has been there all along.

Do not know how to optimize your agent skills? `skillc` helps you with detailed tracing and stats.

Gabriel Wu — Fri, 30 Jan 2026 13:46:09 +0000

Gabriel Wu

Jan 30

Introducing skillc: The Development Kit for Agent Skills

#skill #agents #cli #rust

Comments

3 min read

Introducing skillc: The Development Kit for Agent Skills

Gabriel Wu — Fri, 30 Jan 2026 12:47:42 +0000

TL;DR: skillc helps you create, validate, and optimize reusable knowledge packages that make AI coding agents smarter. Whether you're building skills or consuming them, skillc gives you the tools to work confidently.

The Problem: AI Agents Forget Everything

You've probably noticed this pattern:

You explain a complex workflow to your AI coding agent
It helps you perfectly... this one time
Next session, you explain it all over again

AI agents are stateless. They don't remember your team's conventions, your favorite libraries, or that obscure API you've mastered. Every conversation starts from zero.

Agent Skills: Persistent Knowledge for AI Agents

Agent Skills solve this by giving agents persistent, structured knowledge they can reference across sessions. A skill is just a directory with a SKILL.md file:

rust-skill/
├── SKILL.md          # Metadata + instructions
└── docs/
    ├── patterns.md   # Your coding patterns
    └── gotchas.md    # Common pitfalls

The agent reads your skill and applies that knowledge contextually. No more repeating yourself.

Enter skillc: The Development Kit

skillc is the CLI toolkit for working with Agent Skills. It handles two distinct workflows:

For Skill Authors: Build with Confidence

Creating a skill that actually helps agents requires validation. skillc provides the full authoring pipeline:

skc init  →  skc lint  →  skc build  →  skc stats  →  git push
    ↓            ↓            ↓             ↓             ↓
scaffold    validate    test locally   trace usage    publish

# Create a new skill
skc init rust-patterns

# Validate structure, links, and quality
skc lint rust-patterns

# Build locally and test with your agent
skc build rust-patterns

# See how agents actually use your skill
skc stats rust-patterns --group-by sections

# Publish when ready
git push origin main

The skc stats command is particularly powerful — it shows you which sections agents access most:

$ skc stats rust-patterns --group-by sections

Skill: rust-patterns
Path: /Users/dev/.skillc/skills/rust-patterns
Query: Sections
Filters: since=<none>, until=<none>, projects=<none>
Period: start=2026-01-15T09:12:33+00:00, end=2026-01-30T16:45:21+00:00
23      SKILL.md        Error Handling
18      SKILL.md        Iteration
12      SKILL.md        Lifetimes
9       references/async.md     Tokio Patterns
7       references/async.md     Channel Selection
5       references/testing.md   Mocking Strategies
3       references/testing.md   Property Testing

Now you know: agents need more content on error handling and iteration. This data helps you optimize for real usage patterns.

For Power Users: Unlock Search and Analytics

Even if you're just using skills, skillc adds superpowers:

skc build  →  skc search  →  skc stats
     ↓             ↓              ↓
  indexing    find content   track usage

# Install any skill
npx skills add username/awesome-skill

# Compile it to enable indexing
skc build awesome-skill

# Full-text search across all content
skc search awesome-skill "error handling"

# Track what your agents are actually reading
skc stats awesome-skill

Building a skill creates a search index, so you can quickly find relevant content without reading everything manually.

Real-World Example: A Rust Skill

Here's a minimal but useful skill for Rust development. First, the SKILL.md frontmatter:

---
name: rust-patterns
description: "Idiomatic Rust patterns and common gotchas"
---

Then the content with practical patterns:

Error Handling section:

Always use thiserror for library errors and anyhow for applications:

// Library code
#[derive(thiserror::Error, Debug)]
pub enum MyError {
    #[error("invalid input: {0}")]
    InvalidInput(String),
}

// Application code
use anyhow::{Context, Result};

fn main() -> Result<()> {
    do_thing().context("failed to do thing")?;
    Ok(())
}

Iteration section:

Prefer iterators over manual loops:

// ❌ Avoid
let mut results = Vec::new();
for item in items {
    results.push(transform(item));
}

// ✅ Prefer
let results: Vec<_> = items.iter().map(transform).collect();

After publishing, any agent with this skill installed will apply these patterns automatically.

MCP Integration: Direct Agent Access

skillc includes an MCP (Model Context Protocol) server, so agents can query skills directly. Add it to your agent's MCP configuration:

For example, in Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "skillc": {
      "command": "skc",
      "args": ["mcp"]
    }
  }
}

This exposes tools like skc_search, skc_show, skc_outline, and skc_stats that agents can call programmatically — no CLI needed.

Getting Started

# Install
cargo install skillc

# Create your first skill
skc init my-first-skill --global

# Edit SKILL.md with your knowledge
# Then validate and test
skc lint my-first-skill
skc build my-first-skill

What Will You Teach Your Agent?

The best skills come from real expertise:

Framework patterns you've learned the hard way
API quirks that aren't in the docs
Team conventions that keep code consistent
Debugging techniques for specific tools

Your knowledge, captured once, applied forever.

Links:

What skill would you create first? Drop a comment below!

I Built a CLI Because Cursor Keeps Losing My Chat History

Gabriel Wu — Mon, 19 Jan 2026 09:49:10 +0000

You know that feeling when you rename a project folder and suddenly weeks of AI conversations just... vanish?

I do. It happened to me three times before I decided to fix it.

The Problem Nobody Talks About

Cursor IDE is incredible. But it has a dirty secret: your chat history is tied to your folder path.

Rename my-project to my-awesome-project? Gone.
Move it from ~/dev/ to ~/projects/? Gone.
Clone it to a new location? Gone.

The data isn't deleted — it's still sitting in ~/Library/Application Support/Cursor/User/workspaceStorage/(for MacOS). But Cursor can't find it anymore because the path changed.

I searched for solutions. Found forum posts with manual workarounds:

Find the old workspace folder by hash
Copy contents to the new folder
Edit workspace.json to update the path
Pray it works

That's insane. So I built a tool.

The Fix: One Command

cargo install cursor-helper
cursor-helper rename /old/path /new/path

# Or copy if you want to keep the old folder
cursor-helper rename -c /old/path /new/path

That's it. Your chat history, workspace settings, MCP cache — everything stays intact.

What Else It Does

Export Chats (With the Good Stuff)

Cursor's built-in export strips out thinking blocks and tool calls. Mine doesn't.

# Full export with AI reasoning, tool calls, and token counts
cursor-helper export-chat /path/to/project -v > full-chat-history.md

Output includes:

### 💭 **Thinking** _12.3s_

<details>
<summary>Click to expand thinking...</summary>

The user wants me to refactor the authentication module...
</details>

### 🔧 **Tool: edit_file** [completed]

<details>
<summary>Parameters</summary>

{"path": "src/auth.rs", "old_string": "...", "new_string": "..."}
</details>

This is useful for:

Documenting how you solved complex problems
Training yourself (or others) on AI-assisted workflows
Keeping receipts when the AI does something clever (or dumb)

List All Your Projects

cursor-helper list --sort chats --limit 10

┌──────────┬────────────────────────────────┬───────┬──────────────────┐
│ Remote   │ Path                           │ Chats │ Modified         │
├──────────┼────────────────────────────────┼───────┼──────────────────┤
│ -        │ /Users/me/projects/cursor-help │ 47    │ 2026-01-19 16:04 │
│ tunnel   │ /home/user/big-project         │ 23    │ 2026-01-18 09:30 │
│ ssh      │ /workspace/client-work         │ 12    │ 2026-01-15 14:22 │
└──────────┴────────────────────────────────┴───────┴──────────────────┘

Clean Up Orphaned Data

Deleted some projects? Cursor keeps the workspace data forever.

cursor-helper clean --dry-run

Found 8 orphaned workspace(s):

  /Users/me/.../abc123def456 (234.5 MB)
    Original: file:///Users/me/deleted-project

Total: 1.2 GB in 8 item(s)

Reclaim that disk space.

How It Works

Cursor stores workspace data in two places:

workspaceStorage/<hash>/ — Chat history, settings, state
~/.cursor/projects/<folder-id>/ — MCP cache, terminal info

The hash is computed as MD5(absolutePath + birthtimeMs). When you rename a folder, the path changes, the hash changes, and Cursor creates a new empty workspace.

cursor-helper:

Finds the old workspace by scanning for matching folder URIs
Moves/copies the project folder
Moves/copies the workspace data to the new hash location
Updates workspace.json with the new path
Updates globalStorage/storage.json with the new workspace reference

All in one command.

Installation

# From crates.io
cargo install cursor-helper

# Or grab a binary from GitHub Releases

Works on macOS, Linux (experimental), and Windows.

The Catch

Cursor must be closed when running write operations (rename, clone, backup, restore, clean).

Why? Cursor uses SQLite with WAL mode and keeps databases locked while running. If you modify files while it's open, you risk corruption or Cursor overwriting your changes on exit.

Read-only commands (list, stats, export-chat) work fine while Cursor is running.

Compared to Alternatives

Tool	What it does	Rename support?
cursor-helper	Workspace management + export	✅ Yes
SpecStory	Auto-save chats to Markdown	❌ No
cursor-chat-transfer	Copy chats between workspaces	❌ No
cursor-chat-browser	Browse/export chat history	❌ No

cursor-helper is the only tool that solves the rename/move problem.

govctl: Opinionated CLI tool to enforce RFC-driven AI coding

Gabriel Wu — Sat, 17 Jan 2026 22:22:44 +0000

The Problem

AI coding assistants are fast. They're also completely undisciplined.

Here's a pattern I've seen (and lived) too many times:

Day 1:  "Let's add caching!"
Day 2:  AI generates 500 lines of Redis integration
Day 7:  "Wait, did we agree on Redis or Memcached?"
Day 14: Half the team implements one, half the other
Day 30: Two incompatible caching layers, no spec, nobody knows why

The AI didn't cause this. We did — by skipping the specification phase.

AI amplifies whatever workflow you feed it. Feed it chaos, get chaos faster. Feed it discipline, get discipline faster.

I chose discipline.

The Insight

Every sustainable software project I've worked on had one thing in common: specification preceded implementation.

Not because of bureaucracy. Because clarity compounds.

When you write down what you're building before how, you:

Force yourself to think through edge cases
Give reviewers something to review before 5,000 lines of code exist
Create an audit trail for future maintainers (including future you)

The problem? Nothing enforces this. "Best practices" are suggestions. Suggestions get skipped when deadlines hit.

So I built a tool that doesn't suggest. It enforces.

The Solution: govctl

govctl is a governance CLI that enforces phase discipline on software development.

The core model:

┌─────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  SPEC   │ ──► │   IMPL   │ ──► │   TEST   │ ──► │  STABLE  │
└─────────┘     └──────────┘     └──────────┘     └──────────┘

Phases cannot be skipped. Gates are checked, not suggested.

The Workflow

# Start with a specification (RFC)
govctl new rfc "Caching Strategy"

# Add clauses — atomic units of specification
govctl new clause RFC-0001:C-SCOPE "Scope" -s "Specification" -k normative

# Edit the clause
govctl edit RFC-0001:C-SCOPE --stdin <<'EOF'
The system MUST use Redis for session caching.
The TTL MUST be configurable via environment variable.
Cache invalidation MUST occur on user logout.
EOF

# Lock the spec
govctl finalize RFC-0001 normative

# NOW you can implement
govctl advance RFC-0001 impl

# Validate everything
govctl check

If you try to implement against a draft RFC, govctl check fails. That's the point.

What It Manages

govctl handles three artifact types:

Artifact	Purpose
RFCs	Normative specifications — what will be built
ADRs	Architecture Decision Records — why decisions were made
Work Items	Task tracking with acceptance criteria

All stored as structured data (JSON/TOML), rendered to human-readable Markdown.

The Proof: Dogfooding

govctl governs itself.

Every feature in the CLI was specified in an RFC before I wrote a line of code:

You can trace any line of code back to its specification. This isn't documentation — it's proof that the model works.

Who This Is For

✅ Teams frustrated by AI "code now, think later" patterns
✅ Projects where specs drift from implementations
✅ Organizations needing audit trails for AI-generated code
✅ Developers who believe discipline enables velocity
❌ Not for "move fast and break things" workflows
❌ Not for projects without review processes

This isn't for everyone, and that's okay.

Getting Started

# Install
cargo install govctl

# With TUI dashboard
cargo install govctl --features tui

# Initialize
govctl init

# Create your first RFC
govctl new rfc "My Feature"

# Validate
govctl check

Full documentation: govctl User Guide

Why a CLI?

I considered building an MCP integration, a VS Code extension, a web app.

Then I realized: every AI coding agent already speaks shell.

Claude, Cursor, Codex, Copilot — they can all run commands. The CLI is the universal interface. No JSON-RPC negotiation. No custom protocols. Just:

govctl new rfc "Feature Title"
govctl check
govctl advance RFC-0010 impl

Complexity avoided. Capability preserved.

AI-Native: Embedded Claude Commands

govctl ships with a built-in Claude command that teaches AI agents the complete governed workflow.

Just type /gov add user authentication and Claude will:

Create or activate a work item
Check if an RFC is needed
Create the RFC with proper clauses
Ask permission before advancing phases
Implement the feature
Run tests
Tick acceptance criteria
Mark the work item done

The command encodes the entire workflow — phase discipline, RFC supremacy, commit conventions — so the AI follows governance rules automatically.

# In Cursor or Claude Code
/gov implement caching with Redis

The AI becomes a constrained autonomous agent that respects your governance model.

Built With

Rust (edition 2024) — for correctness and speed
Clap — CLI framework
Serde — serialization
Ratatui — optional TUI dashboard

MIT licensed. Contributions welcome.

Final Thought

AI coding tools are here to stay. The question isn't whether to use them — it's how to use them without losing control.

govctl is my answer: specification-first, phase-gated, governance as code.

If that resonates, give it a try:

👉 github.com/govctl-org/govctl

"Discipline is not the opposite of creativity. It is the foundation."

Compile OpenCV4

Gabriel Wu — Mon, 06 May 2019 11:53:18 +0000

Since OpenCV4 does not generata .pc file by default, we need to compile it from source and turn on the OPENCV_GENERATE_PKGCONFIG option if other programs need the pkg-config file.

Another problem I encountered is a number of errors similar to undefined reference to TIFFReadRGBAStrip@LIBTIFF_4.0. To solve that, the BUILD_TIFF option needs to be turned on.

And following is the script for compilation and installation.

wget https://github.com/opencv/opencv/archive/4.1.0.zip
unzip opencv-4.1.0.zip
cd opencv-4.1.0
mkdir build && cd build
cmake -D CMAKE_BUILD_TYPE=Release -D OPENCV_GENERATE_PKGCONFIG=YES -D CMAKE_INSTALL_PREFIX=/usr/local -D BUILD_TIFF=ON
sudo make -j`nproc`
sudo make install

My GDAL CLI snippets

Gabriel Wu — Thu, 07 Mar 2019 15:05:17 +0000

To crop a raster file according to a shapefile

gdalwarp -overwrite -s_srs EPSG:32649 -q -cutline shapefile.shp -of GTiff raw.tiff crop.tiff

To merge several bands into a raster file

gdal_merge.py -o target.tiff -of GTiff -ps 10 10 -separate B1.tiff B2.tiff B3.tiff

Here 10 10 means 10 meters in the x-axis and 10 meters in the y-axis. If -ps is not specified, the spatial resolution of the first raster file will be considered to be the target resolution.

To merge several files spatially

gdal_merge.py -o target.tiff -of GTiff TL.tiff BL.tiff TR.tiff BR.tiff

To resample a raster file

gdal_translate -outsize 50 50 raw.jp2 target.jp2

Here 50 50 means 50% in x-axis, and 50% in y-axis.

Appendix: Install GDAL for Python on Ubuntu

# Install gdal library
sudo apt-get install -y gdal-bin libgdal-dev
# gdal-bin is not necessary, but you will definitely need it to run the CLI commands above

# Export include path
export CPLUS_INCLUDE_PATH=/usr/include/gdal
export C_INCLUDE_PATH=/usr/include/gdal

# Install the exact version of Python package
gdal-config --version | xargs -0 -I {} pip install gdal=={}

How I wrote my own React wrapper for Google Map

Gabriel Wu — Wed, 27 Feb 2019 13:27:00 +0000

A few months ago, when I started the Neighborhood Map project of Udacity, I first checked the libraries available. There were quite a few choices:

However, none of them could meet my requirements (it was also possible that I did not figure out the proper way to deal with the problems). I want the components to be flexible, e.g., the Marker component does not necessarily to be placed within a Map component. This flexibility is essential when designing the layouts, and also when structuring components so as not to trigger unnecessary rerender.

What they provide (generally):

<Map>
    <Marker />
    <InfoWindow />
</Map>

What I want:

<Map />
<ComponentA>
    <Marker />
    <ComponentB>
        <InfoWindow />
    </ComponentB>
</ComponentA>

The idea came into my mind that I could write my own React wrapper for Google Map. This sounded a bit audacious because I had never written a React component library before. As the deadline of the Udacity project came closer and closer, I finally made up my mind to write my own Google Map library, with React hooks and TypeScript, and TDD.

Although I had not written a React component library, I had written a very simple Vue component library (following instructions of a blog). I had been writing TypeScript for several months, and had written a React app with context and hooks. And I had used TDD in several projects. These experiences gave me confidence.

Yet challenges did come, one after another. I had written some tests, but I had not written library mocks. I managed to mock loadjs, which I used to load Google Map scripts.

Another problem was that hooks live with functional components, and functional components do not have instances. Other Google Map libraries all use class components, and implement methods for class instances to surrogate Google Map objects' methods. But I could not do so. In the end, I chose to maintain an id-object Map to store references to all Google Map objects. It worked fluently, and could be used without using React ref (class instances rely on ref). The only price was that things like Marker, Polygon would require a unique id when using my library.

At first, I just thought about my own needs, and the API design was way too casual (you can check my original repo and time-travel to earlier versions). Later, my personal project was finished, but I knew a lot of things were still up in the air.

lucifer1004 / boycott

A map app.

Boycott

This is a Udacity project. It is statically deployed here via Now.

To run it locally

git clone https://github.com/lucifer1004/boycott
cd boycott
yarn install
yarn start

You can then visit it at localhost:3000

Features

Search for places using Yelp Fusion API (cors-anywhere is used to address the CORS issue)
Filter options: All/Open/High Rating/Low Price
Use of Google Map API is via @lucifer1004/react-google-map, which is a React wrapper for Google Map written by myself.

View on GitHub

It is a simple React app, using Google Map and Yelp to implement basic place search.

After submitting the project at Udacity, I went on with my library. For my personal project's needs, I only implemented MapBox, Marker, InfoWindow, HeatMap and Polygon. There were around 20 more Google Map components.

It happened several times that I had to refactor the whole library when trying to implement a new component. Luckily, I wrote unit tests for each component, and those tests helped a lot during refactors.

I spent about two weeks' spare time implementing:

other shapes: Circle, Polyline, Rectangle
layers: BicycleLayer, TrafficLayer, TransitLayer
search: SearchBox, StandaloneSearchBox
streetview: StreetView, StandaloneStreetView
overlays: CustomControl, GroundOverlay, KmlLayer, OverlayView
drawing: DrawingManager

The library started from create-react-app, I used a separate package.json in src/lib to configure the library, while the app was configured by the root level package.json. As the library grew, I felt I should set up a monorepo properly.

The week of refactoring project structure was rather tough. I read many blogs and posts on monorepos, but still could not get everything work as I hoped. I gave up once, and nearly gave up again the second time, and I made it.

With lerna and yarn workspaces, and a custom symlink，I was finally pleased with the new structure. By running yarn dev:lib and yarn dev:CRA at the same time, the example CRA app would reload each time I changed the code of the library.

I really appreciate that I decided to write my own wrapper library a month ago, otherwise I would not have learnt so much (I am going to write more posts in the series to talk about things I have learnt in detail). And I will try to further improve my library. It has not been tested in real projects. Compared to existing libraries, some functions are missing. Also there are some known issues, or limitations.

I am prepared.

Recently, I moved this project to a separate organization. Below is the repo.

googlemap-react / googlemap-react

Easier Google Map Integration for React projects.

googlemap-react

Easier Google Map Integration for React projects.

READ THE DOC

Why a new package

There has been similar packages such as tomchentw/react-google-maps google-map-react/google-map-react fullstackreact/google-maps-react so why bother writing a new library?

The aim is to make an easier-to-use Google Map library for React users, empowered by React's latest features (React >= 16.8.0 is required) and TypeScript.

What is different

Component position is free (generally)
Direct access to Google Map objects
More uniform API
Type safe

Example usage

Prerequisites

npm or yarn

yarn add @googlemap-react/core
# Or you can use
npm install --save @googlemap-react/core

a valid Google Map API key (to replace the place holder in the code snippet below)

import {
  GoogleMapProvider
  HeatMap,
  InfoWindow,
  MapBox,
  Marker,
  Polygon,
} from '@lucifer1004/react-google-map'

// In your component
return (
  <GoogleMapProvider>
    <MapBox
      apiKey="YOUR_GOOGLE_MAP_API_KEY

…

View on GitHub

Any advice or suggestions are welcome! If you want to use my library and run into any problem, just ask me!

If you want to join, that would be great!

Simple way to diff server/browser rendering results

Gabriel Wu — Sun, 24 Feb 2019 11:00:52 +0000

I found this answer at StackOverflow. I think it is useful, so I share with you here.

Browser side

First of all, you should ensure the site is served. Then you can:

Open your site in any browser
Open the browser console, and type:

console.log(document.documentElement.innerHTML)

Copy the output, and save it as client.html

Server side

Supposing your site is running on localhost:3000.

Open a shell, and type:

curl localhost:3000 > server.html

Compare the differences

You can simply run:

diff client.html server.html

Note that you may need to format both files before diff.

It is NOT always right to pin your dependencies

Gabriel Wu — Tue, 19 Feb 2019 01:21:30 +0000

TL;DR;
If you are writing a library/package, make sure you will update your dependencies in time before pinning all dependencies. Otherwise, issues may be caused.

You might have used tools like renovate to manage dependencies of your GitHub repository. The first thing it will do is to pin your dependencies.

Pinning dependencies can:

Avoid potential bugs caused by upstream package/library updates. (Such bugs are still possible because upstream packages may not have pinned their dependencies.)
Help your collaborators or people who are interested in your project to reproduce your dev environment. (It will be even sweeter if combined with docker.)

However, it can also cause issues sometimes. And I am going to share with you a recent experience.

I am doing a Google Map project, and I have two repositories for this. (I tried lerna, but failed to get everything to work well and had to give up.)

One is a React wrapper around Google Map API:

lucifer1004 / react-google-map

Easier Google Map Integration for React projects.

React Google Map

Easier Google Map Integration for React projects.

NOTE

This project has been moved to @googlemap-react.

READ THE DOC

Why a new package

There has been similar packages such as tomchentw/react-google-maps, google-map-react/google-map-react, fullstackreact/google-maps-react, so why bother writing a new library?

The aim is to make an easier-to-use Google Map library for React users, empowered by React's latest features (React >= 16.8.0 is required) and TypeScript.

What is different

Component position is free (generally)
Direct access to Google Map objects
More uniform API
Type safe

Example usage

Prerequisites

npm or yarn

yarn add @lucifer1004/react-google-map
# Or you can use
npm install --save @lucifer1004/react-google-map

a valid Google Map API key (to replace the place holder in the code snippet below)

import {
  GoogleMapProvider,
  HeatMap,
  InfoWindow,
  MapBox,
  Marker,
  Polygon,
} from '@lucifer1004/react-google-map'
// In your component
return (

…

View on GitHub

The other is the application:

lucifer1004 / boycott

A map app.

Boycott

This is a Udacity project. It is statically deployed here via Now.

To run it locally

git clone https://github.com/lucifer1004/boycott
cd boycott
yarn install
yarn start

You can then visit it at localhost:3000

Features

Search for places using Yelp Fusion API (cors-anywhere is used to address the CORS issue)
Filter options: All/Open/High Rating/Low Price
Use of Google Map API is via @googlemap-react/core, which is a React wrapper for Google Map written by myself.

View on GitHub

For both repositories, the dependencies are pinned. One day, to my surprise, all my React hooks failed to work. Such error messages kept occurring:

React Hooks Error: Hooks can only be called inside the body of a function component...

They provided no useful information at all! I WAS calling hooks inside the body of functional components.

After a tough search, I finally found something inspiring. This error can occur when there is React version inconsistency. I then checked package.json of both the library repo and the application repo, and found that the library was using React 16.8.1 while the application was using React 16.8.2. I quickly updated my library to use React 16.8.2, and then the errors went away.

Now, I have moved react and react-dom to peerDependencies and relaxed the version restrictions to ^16.8.2. I think this is enough to prevent similar issues.

What I have learned from this experience is that something GOOD (pinning dependencies) is not always RIGHT. It DEPENDS! Dependency pinning is GREAT for an application. However, you should be more CAREFUL when writing a library/package.