JTianling's Blog

cross-agent-teams: a local message bus that lets multiple coding agents talk to each other

2026-05-01T21:00:00+08:00

These days I usually have several coding agents running on the same machine: Claude Code doing the main development, Codex on the side for review or longer jobs, sometimes an opencode session for something else. The tools themselves are fine. What’s actually missing is any official way for them to talk to each other. If Codex finds something it wants to tell the Claude Code session, I have to copy-paste it myself. Claude Code, being a pure TUI agent, has no standard “wake from outside” entry point either — you can leave it a message, but its CLI does not beep, so the user has to switch windows manually to even see it.

After enough of that friction, I built a small local MCP daemon, cross-agent-teams-mcp (the project nickname is xats), to give every coding agent on the machine a shared mailbox and wake channel. Each agent still runs in its own native CLI, no harness changes; the daemon only handles “carrying messages” and “knocking on the door”.

Repo: https://github.com/jtianling/cross-agent-teams-mcp

What it is, in one sentence

cross-agent-teams-mcp is a local MCP daemon. Multiple coding agents on the same machine (Claude Code, Codex, opencode, cursor, …) each register it as an MCP server, and then they can DM each other by name, team, or role, or broadcast within a team. The daemon also pushes messages back to the recipient so it can wake itself up to read them. No external service is involved; everything lives in a single SQLite file at ~/.cross-agent-teams-mcp/data.db.

Why I built it

The pain points were specific, not “I want a multi-agent framework”:

Calling between Codex and Claude Code meant copy-paste by hand. Context kept getting lost on the round trip.
Claude Code has no standard “wake from outside” entry point. You can leave it a message, but the CLI does not notify; the user has to switch back to see it.
I’d worked around it with tmux send-keys, but that means hand-maintaining a pid-to-pane mapping, and it only works for plain TUI agents — Claude Code is its own thing again.
Multiple agents have no shared context, so every new session has to re-paste the same background.

So xats is deliberately narrow: give the coding agents already running on this machine a shared mailbox and wake channel. Nothing else.

How it differs from existing things

I want to draw a clear line against a few things that are easy to confuse it with:

Claude Code’s built-in sub-agent / Task tool: that’s a parent–child relationship — one Claude instance forks a short-lived sub-agent, used and discarded, no cross-harness story. xats is horizontal communication between peer agents, each of which is its own long-running session.
codex --remote: that just connects Codex’s TUI to a remote Codex process. Still one agent talking to itself. xats doesn’t replace any agent’s runtime.
autogen / crewai and similar multi-agent frameworks: those are orchestrators — the framework owns the agent loop, and you write Python around it. xats works the other way around: every agent keeps running in its native CLI (Claude Code is still Claude Code’s TUI, Codex is still Codex’s TUI), and the MCP daemon only handles inbox and wake. No language lock-in, no need to migrate code into a framework.

One-line positioning: a local message bus for already-running coding agents, not a multi-agent framework.

Two technical bits worth mentioning

The Claude Code channel-proxy

Claude Code has an experimental capability called notifications/claude/channel. It only turns on if you launch with --dangerously-load-development-channels server:<name>. The trouble is that the daemon itself is an HTTP server, while Claude Code talks to MCP servers over stdio — the two don’t connect directly.

The fix is a small stdio shim, published alongside the daemon as cross-agent-teams-channel. Claude Code starts it as if it were a normal MCP server; internally the shim opens a long-lived connection to the daemon and feeds wake events back to Claude Code over the channel transport. From the user side there’s nothing to configure beyond adding both the daemon and the shim entries to .mcp.json.

A subtlety worth recording: when the shim starts, it generates a channel_session_id (csid) for itself and registers process.ppid (which is the Claude Code CLI’s own pid) on the proxy row in the daemon. Later, when Claude Code’s business side calls register_agent and passes ui_pid=$PPID, the daemon looks up the matching proxy by ui_pid and auto-binds the csid for it — the user never copies a csid by hand, and there’s no risk of multiple Claude instances silently mis-binding to each other’s channels (a bug I had to track down once; not at all obvious from the symptoms).

pid → tty → pane tmux wake

For agents without a push channel — opencode, cursor, or a Codex without app-server — the wake path has to fall back to something simple: paste a short line of text into the tmux pane the agent is sitting in.

The flow is: take ui_pid at registration time, look up its tty via /dev/ttys, then map tty → pane id with tmux list-panes -F, and cache it. When send_message triggers a wake, just tmux send-keys into that pane. The idea is unsurprising; the pitfalls are the interesting part. The tty ps reports on macOS doesn’t always match what tmux uses literally; wrapping with npx makes process.ppid point at npm rather than Claude Code; and so on. The current implementation walks the process tree up until it finds the real host pid.

What works today

The following are stable and what I use every day:

register_agent with auto-detection of claude-code / codex / custom
send_message for 1→1 DMs by name or agent id
broadcast and broadcast_to_role within a team
get_inbox to read mail
list_agents to see who’s around
Wake channels: Claude Code via channel push, Codex via app-server WebSocket (when started) or tmux paste otherwise, opencode/cursor/custom via tmux paste
ui_pid auto-binds the channel, with the daemon rejecting csid mismatches up front

Two more areas are implemented but not promoted in the README yet, because I haven’t lived on them long enough:

A shared task list (task_add / task_list / task_claim / task_complete)
Contracts (register_contract / subscribe_contract / diff_contracts) for lightweight cross-agent interface descriptions

I’ll add them to the README once they earn it.

Getting started

The fastest path is daemon + mcpsmgr in three commands, no hand-editing of .mcp.json required.

Claude Code (default):

# 1. Start the daemon (run once, keep it alive — dedicated terminal, tmux, launchd, your call)
npx -y cross-agent-teams-mcp@latest daemon --port 9100 &
# 2. From your project, let mcpsmgr install the MCP config (it edits the project's .mcp.json)
npx mcpsmgr add jtianling/cross-agent-teams-mcp -a claude-code
# 3. Launch Claude Code with the channel loader (you'll be prompted to approve the capability)
claude --dangerously-load-development-channels server:cross-agent-teams-channel

Other agents (Codex, opencode, …):

npx -y cross-agent-teams-mcp@latest daemon --port 9100 &
npx mcpsmgr add jtianling/cross-agent-teams-mcp     # interactive: pick the agent
# Then start the coding agent as usual

A heads-up: these agents don’t have Claude Code’s channel push transport, so the daemon falls back to tmux paste when delivering wake events (Codex with app-server is the exception). In practice you’ll likely have to nudge the agent to call get_inbox yourself from time to time — something as casual as “check my inbox” works. For more native waking on Codex, run its app-server alongside (covered in “Detailed reference” below).

Once inside an agent session, you don’t need to memorize tool names — just talk to it:

# Agent A: Register me to xats as backend on team default.
# Agent B: Register me to xats as frontend on team default.
#         Send backend a message: the API has changed.

The agent picks the right tool (register_agent, send_message, get_inbox, …) on its own.

Note: the name after --dangerously-load-development-channels server: must match the channel shim’s server key in .mcp.json, which is cross-agent-teams-channel by default.

Detailed reference

The daemon listens on 9100 by default; pass --port to change it:

npx -y cross-agent-teams-mcp@latest daemon --port 9300

Recommended: install the MCP config with mcpsmgr

npx mcpsmgr add jtianling/cross-agent-teams-mcp -a claude-code writes both Claude Code entries (the HTTP endpoint and the channel shim) into the project’s .mcp.json automatically. Drop the -a flag to get an interactive picker for the agent type (codex, opencode, cursor, …).

If you’ve changed the daemon port (e.g. to 9300 above), tweak the daemon URL afterwards via env var or by editing .mcp.json directly — the file is plain JSON, so post-hoc tweaks are fine.

Manual .mcp.json

If you’d rather not involve mcpsmgr, you can hand-write it. Claude Code needs two entries — the HTTP endpoint plus the channel shim:

{
  "mcpServers": {
    "cross-agent-teams": {
      "type": "http",
      "url": "http://127.0.0.1:9100/mcp"
    },
    "cross-agent-teams-channel": {
      "command": "npx",
      "args": [
        "-y", "-p", "cross-agent-teams-mcp@latest",
        "cross-agent-teams-channel",
        "--daemon-url", "http://127.0.0.1:9100/mcp"
      ]
    }
  }
}

Codex is a little different. Tool calls themselves only need a streamable-http entry in ~/.codex/config.toml; no channel proxy:

[mcp_servers.cross-agent-teams]
type = "streamable-http"
url = "http://127.0.0.1:9100/mcp"

But if you want other agents to be able to wake this Codex thread, instead of only mailing it and waiting for the user to come back, there’s one more step: run Codex’s own app-server alongside the TUI. This uses Codex’s native websocket protocol (the codex-appserver transport), and a wake there literally means “start a turn inside that thread” — quite a bit cleaner than tmux paste. The rough shape:

codex app-server --listen ws://127.0.0.1:8799     # one terminal: app-server
codex --remote ws://127.0.0.1:8799                # another terminal: TUI connects in

Those two lines aren’t enough on their own — the real setup is more involved. Three key gotchas:

Under --remote, MCP servers are loaded by the app-server, NOT by the TUI. So the cross-agent-teams-mcp entry has to live in the CODEX_HOME that the app-server reads at startup (usually the global ~/.codex/config.toml). Setting CODEX_HOME on the TUI side does nothing.
~/.codex/config.toml needs experimental_use_rmcp_client = true at the top, or streamable-http MCP servers won’t load at all.
For wake events to actually be injected into the codex thread (instead of still falling through to tmux paste), launch codex via a wrapper that calls pre-register-codex-pane so the daemon can map this codex process to its tmux pane.

The zsh launcher I personally use (with header comments and prereq notes) lives in a gist — source it or paste it into ~/.zshrc: https://gist.github.com/jtianling/6c2769f76ffb8fbff8856f90dc7f9554. The full step-by-step (MCP entries, start order, etc.) is in the repo README under “Let other agents wake you (codex-appserver poke)”.

Once that’s all wired up, Codex calls register_agent from inside its session, and the daemon records its thread_id as a codex-appserver delivery (Codex 0.124.0+ exports CODEX_THREAD_ID to MCP tools automatically, so registration just picks it up). After that, when xats pushes a message to this Codex, it goes over websocket — no tmux involved.

It still works without app-server: the daemon falls back to tmux paste, which is fine but rougher — the wake is literally a line of text pasted into the Codex pane. So my recommendation: if you want this Codex to be wakeable by peer agents, follow the README and wire up app-server + launcher together.

opencode and cursor have no dedicated wake transport and rely on tmux paste; their configs live under docs/configs/.

What’s next (loose plans, not commitments)

Short term: get contracts polished enough to be useful as lightweight cross-agent interface descriptions; actually live on the shared task list.
Medium term: cross-machine. Right now everything is strictly localhost; once it goes off-box, auth, isolation, and proxying all need a fresh design pass.
Not planning to do: an agent orchestration framework. The boundary stays at transport + inbox; how agents collaborate is left to the user’s own prompts and workflow.

Already dogfooding it

xats is already in use on its own development. Several releases leading up to 0.5.0 — including the channel-proxy refactor and the collapse of register_*_self into a single unified register_agent — were done with Claude Code + Codex + xats working together: Claude Code wrote part of the implementation, Codex did review and ran independent checks alongside, and they coordinated progress and findings through xats instead of through me as a human relay. That experience is more convincing than any abstract list of features.

If you’re also juggling several coding agents on the same machine and have hit the “they can’t talk to each other” wall, give it a try. Feedback welcome.

Agent of Empires: A tmux-Based AI Agent Session Manager

2026-03-30T15:21:39+08:00

I’ve been trying out all kinds of AI coding agents lately. After going back and forth between them, I’ve realized that the real pain point often isn’t the model itself — it’s managing multiple agents at once: who’s working on which branch, what task is each one running, is one stuck waiting for input, do I need to take over, and will it keep running after I close the window? Managing all of this by hand gets messy fast once you have more than a couple of agents going.

After using Agent of Empires for about half a month, I think it’s worth a proper write-up. The name is a bit grand (AoE for short), but what it does is quite practical: rather than building an entire “AI IDE” from scratch, it builds on tmux and git worktree — tools that already work great — to create a session manager specifically for AI agents. AoE recently hit v1.0.0 and has become quite mature overall.

Repository links:

Upstream: https://github.com/njbrake/agent-of-empires
My fork: https://github.com/jtianling/agent-of-empires

In One Sentence

Agent of Empires is essentially an AI agent dispatch panel for your terminal. It runs different agents in their own tmux sessions and can leverage git worktree to work on multiple branches of the same project simultaneously. Currently supported agents include Claude Code, Codex CLI, Gemini CLI, OpenCode, Cursor CLI, Copilot CLI, Mistral Vibe, Pi.dev, Factory Droid CLI, and more — basically all the mainstream terminal AI agents are covered.

Why I Find It Interesting

When doing AI-assisted programming nowadays, the natural workflow is no longer “me and one agent going back and forth.” Instead, it’s more like:

One agent writing features
One agent running tests or fixing lint
One agent doing code review
Another agent looking up docs or organizing thoughts

In this scenario, just opening lots of terminal tabs technically works, but you quickly run into problems: directories get mixed up, branches get crossed, state is hard to track after closing windows, and it’s not easy to tell at a glance whether an agent is busy, waiting, or finished.

Agent of Empires takes a systematic approach to these problems. Here are the features I find most practical:

Built on tmux, so sessions persist — agents keep running after you close the TUI
Integrates with git worktree for parallel work on different branches
Has both a TUI and CLI — you don’t need to stay in the interface full-time
Shows agent status (Running / Waiting / Idle), and you can attach directly to take over
Supports Docker sandbox for more isolated agent environments
Built-in diff view to review agent git changes right in the TUI
Supports sending messages to agents (aoe send) without needing to attach
Per-project .aoe/config.toml for hooks and project-level settings
Sound notifications when agent status changes

In short, it doesn’t try to replace the terminal — it just makes “managing lots of agent terminals at once” much smoother.

What I personally find most valuable is that when I don’t want my coding agents to keep getting interrupted, I can keep them running persistently on a Mac I use as a server. Even when I leave my desk — whether I’m commuting or at home — I can SSH into that Mac, run aoe, and instantly resume my entire working environment. This is also why I haven’t switched to powerful local agent management tools like cmux: while local window splitting and agent management is very convenient, you can’t easily resume a remote session.

Installation and Basic Usage

The upstream README offers several installation methods. The simplest is probably:

curl -fsSL \
  https://raw.githubusercontent.com/njbrake/agent-of-empires/main/scripts/install.sh \
  | bash

Or if you use Homebrew or Nix:

# Homebrew
brew install aoe

# Nix
nix run github:njbrake/agent-of-empires

Once installed, the most direct way to start is:

aoe

You can also add sessions directly from the command line:

# Add a session for the current project
aoe add .

# Add a session in a new worktree / branch
aoe add . -w feat/my-feature -b

# Start in sandbox mode
aoe add --sandbox .

What I like most about this design is that it doesn’t hide the underlying machinery. It’s still tmux sessions underneath, so if anything goes wrong, you can always attach directly and inspect — no “close the UI, everything becomes a black box” feeling.

Who Is It For

I think it’s especially suitable for these scenarios:

You’re already comfortable with a terminal workflow, or at least don’t mind tmux
You run multiple AI agents on the same project
You actively use git worktree or multi-branch parallel development
You want agents that run persistently, not as one-shot Q&A tools

On the flip side, if you don’t usually work in the terminal and aren’t willing to accept the tmux layer of abstraction, the learning curve might feel steep. This tool clearly isn’t made for people who never want to touch a terminal.

What I Changed in My Fork

I started forking fairly early on, with about 90+ commits in total. Early additions included a profile mechanism, terminal title management, and various tmux interaction fixes. Currently, the changes in my fork beyond upstream focus on a few daily experience improvements:

Session navigation keybindings – The upstream AoE has fairly basic navigation between tmux sessions. I added a full suite: Ctrl+. / Ctrl+, for quick session switching (cycling across groups), number keys (1-99) to jump directly to a specific session in both TUI and tmux, and Ctrl+b b to go back to the previous session (similar to vim’s Ctrl+^). Inside tmux, I also added vi-style pane navigation (Ctrl+b h/j/k/l), Ctrl+; to cycle through panes, and Ctrl+Q for one-key detach. With all these shortcuts combined, jumping between multiple agents feels much smoother — you rarely need to go back to the TUI list to select.

Notification Bar – Inspired by Agent Deck, it displays real-time status of all sessions (Running / Waiting / Idle) with status icons directly in the tmux status bar. This way, even when you’re attached to one agent session, you can see at a glance whether other sessions are waiting for your input, without switching back to the TUI. Combined with quick-switch, jumping to a session also automatically acknowledges the Waiting status.

Agent Restart – Press R to restart the agent pane directly without destroying and recreating the entire session. The main use case is agents like Claude Code that need a restart to refresh skill configurations — after editing a skill, just press one key instead of manually exiting and reopening. For Claude Code and Codex, I also implemented graceful resume restart: it persists the resume token so the agent can restore its conversation state after restarting.

Narrow-screen layout – On narrow terminals (iPhone portrait, Mac split-screen, small tmux panes), the TUI automatically hides the preview panel and shows only the session list at full width. When attaching to a session with split panes, the agent pane auto-zooms for a usable full-screen view; returning to a wide terminal auto-unzooms. Pane-switch keybindings (Ctrl+b h/j/k/l, Ctrl+;) are zoom-aware, so switching panes while zoomed re-zooms the target pane seamlessly.

Overall Impression

After using it for about half a month, I think the most valuable thing about Agent of Empires isn’t how many models it supports, but that it addresses a very practical problem: when AI agents go from “occasional use” to “running several in parallel,” what you really need to manage is sessions, state, isolation, and context — not a fancier chat window.

Since reaching v1.0.0, the upstream completeness is quite high. With diff view, per-repo config, sound notifications, and send message all in place, daily use requires very little extra tinkering. If you already work in the terminal and have started getting used to running multiple agents in parallel, this tool is definitely worth a serious try.

dual-yazi: Adding the Dual-Pane Mode I Wanted to Yazi

2026-03-17T21:13:55+08:00

While managing files in the terminal recently, I’ve been feeling a bit torn: on one hand, Yazi, as a next-generation terminal file manager, is genuinely excellent — fast, with great preview capabilities, and a flexible plugin system; on the other hand, if you’ve spent years using dual-pane file managers like Midnight Commander or Total Commander as I have, many operational habits are already ingrained in your muscle memory.

So I went ahead and forked Yazi to create dual-yazi: https://github.com/jtianling/dual-yazi. It’s not a ground-up rewrite of a file manager, but rather an added workflow layer on top of the original Yazi that I wanted most: fixed dual panes, independent tabs per pane, direct cross-pane copy/move, and toggling between single-pane/dual-pane and preview modes.

For me, this was a natural direction. I love Yazi’s modern TUI file management experience, but I’ve always missed the directness of traditional dual-pane managers — having two directories side by side, always in view. Now I’ve finally brought these two worlds together.

Repository links:

Yazi official repository: https://github.com/sxyazi/yazi
My fork: https://github.com/jtianling/dual-yazi

Why Yazi Is Worth the Effort

If you haven’t tried Yazi yet, I think it’s one of the most worthwhile terminal file managers to try in recent years.

The official README lists many features, but what I personally value most are: it’s genuinely fast, with thorough async I/O and task scheduling; the preview capabilities are comprehensive — not just text, but images, PDFs, archives, and syntax-highlighted code are all covered; and the Lua plugin system is open enough that you never feel like “there are lots of features, but I can’t modify anything.”

In other words, it’s not a simple tool that can only do basic hjkl directory browsing, but a terminal file manager that can seriously serve as a daily driver. The reason I want to add dual-pane support is precisely because I think the core is already good enough to build my desired interaction on top of.

Why I Still Want Dual Panes

Tabs are useful, of course, and single-pane + preview already covers many scenarios. But it’s still different from a true dual-pane workflow.

For tasks like sorting a downloads directory, comparing two directory structures, filtering files from one location to move to another, or archiving files while browsing a project directory, the dual-pane mental model is simply more direct: left is source, right is target, whichever pane has focus is where operations take effect. You don’t need to constantly remember “which tab was my target directory in,” and you don’t need to switch back and forth to confirm your current context.

This is why many classic file managers still have loyal users today. They may not be the most modern, but for the problem of “batch file management,” the workflow is incredibly smooth.

What dual-yazi Has Now

1. Dual-Pane Mode

The program starts in fixed dual-pane mode by default, with a pane on each side and the left pane focused initially. Each pane has its own header and status bar, so it’s not simply slicing the original interface in half — each pane is treated as a complete browsing context.

The default dual-pane layout favors directory browsing: each pane shows parent + current, meaning the parent directory column plus the current directory column, with preview hidden by default. The reason is simple — in dual-pane mode, the most common need is usually quick operations between two directories, not viewing large previews.

Pane switching follows familiar conventions:

Tab
Ctrl-w w
Ctrl-w Ctrl-w
Ctrl-w h
Ctrl-w l

2. Per-Pane Independent Tabs

Dual panes and tabs are not mutually exclusive. In dual-yazi, each pane independently maintains its own set of tabs, with its own tab cursor and state. This means you don’t just have two fixed directories — you effectively have two independent workspaces that don’t interfere with each other.

I really like this aspect. For example, the left pane can permanently hold tabs for source code, documents, and downloads, while the right pane holds tabs for archives, temporary directories, and target directories. The directness of traditional dual-pane file managers is preserved, but with an additional layer of flexible organization.

More importantly, Yazi’s original tab operations are mostly preserved. The default keymap includes:

t to create a new tab
Ctrl-c to close the current tab; exits if it’s the last tab
1-9 to switch tabs
[ / ] to cycle through tabs
{ / } to swap tabs

The tab_rename action still exists but doesn’t have a default keybinding — you can bind it yourself in the keymap if needed.

All these operations now apply to the current pane rather than sharing a global tab list.

3. Cross-Pane Copy/Move (MC-style F5/F6)

This was one of the features I most wanted to add.

The original Yazi already has the y / p yank/paste workflow, which works well. But if you’re used to dual-pane managers where you select items on the left and press F5 to copy to the right or F6 to move — you’d want it as a single-key action, not yank, switch pane, then paste.

Here’s what’s provided:

F5: Copy selected items to the other pane’s current directory
F6: Move selected items to the other pane’s current directory

These are direct cross-pane operations that don’t go through the yank register. If nothing is explicitly selected, they operate on the hovered file. The advantage is that it doesn’t disrupt the existing y / p workflow, while providing more MC-like muscle memory in the dual-pane context.

I also mapped F7 / F8 to more traditional semantics: F7 creates a file or directory, F8 trashes items; for permanent deletion, use the original D. With this setup, the terminal file management experience really does feel more like a classic dual-pane manager.

4. Single/Dual Toggle

While I want dual panes most of the time, it’s not always necessary to see both sides.

Ctrl-w o toggles between dual-pane and single-pane mode. One thing I care about here: when switching to single-pane, the other pane isn’t reset — just hidden. Its directory, cursor, selection, and history are all preserved. Switching back to dual-pane restores everything as it was.

This means single-pane mode isn’t “exiting dual-pane” but rather “temporarily focusing attention on the current pane.” You can go single-pane when you need the full width to view content, then switch back to dual-pane for two-directory operations without any context loss.

Also, in single-pane mode, the pane concept still exists. You can still switch the active pane, and you can still target F5 / F6 at the currently hidden pane. I find this quite practical.

5. Preview Toggle

Dual-pane mode defaults to directory browsing, but sometimes you want a quick preview.

Ctrl-w p toggles between two layouts in dual-pane mode:

Directory mode: parent + current
Preview mode: current + preview

This means you can switch both sides to a more “content viewing” layout without leaving dual-pane mode. Use directory mode while organizing files, switch to preview mode when you need to check file contents — both stay within the dual-pane workflow.

I find this more ergonomic than a fixed dual-pane layout. Otherwise, dual-pane easily becomes a mode that can only “move files” rather than a main interface you can use long-term.

6. Undo/Redo

This feature is also crucial.

F5 / F6 in a dual-pane manager are very convenient, but to confidently manage files in bulk, you need an “undo button.” dual-yazi now supports u for undo and Ctrl-r for redo. Not just rename, create, copy, move, and trash — the copy_to / move_to operations from dual-pane mode also go into the undo stack.

Of course, undo currently isn’t universal. Permanent delete D, shell commands, bulk rename, and operations performed by plugins are not covered by this undo system. But for the file management actions I use most frequently, it’s more than sufficient.

How to Try It

The easiest path is via my personal Homebrew tap:

brew install jtianling/tap/dual-yazi

Or brew tap jtianling/tap first and then brew install dual-yazi — same result. It works on macOS (Apple Silicon / Intel) and Linuxbrew. There’s no prebuilt bottle yet, so the first install compiles the Rust project from source — about 5-10 minutes on my machine. Upgrades go through brew upgrade dual-yazi like anything else.

One thing to be aware of: the binaries are still named yazi and ya, the same as upstream, and the formula declares conflicts_with "yazi". The upside is that every keymap, plugin, and doc that references the yazi command keeps working unchanged; the cost is that the two can’t coexist. If you already have the official Yazi installed:

brew uninstall yazi
brew install jtianling/tap/dual-yazi

If you’d rather skip brew, or you’re used to building Rust projects from source, you can also build it directly:

git clone https://github.com/jtianling/dual-yazi.git
cd dual-yazi
cargo install --path ./yazi-fm
yazi

If you’re already using the original Yazi, you can treat this as an experimental branch to try. Whether or not you like the dual-pane workflow, half an hour of use should be enough to tell.

In short, I’m not trying to prove that “dual-pane is inherently better than single-pane.” I just wanted to bring a file management habit I’ve used for many years back into a modern tool I already love. For me, dual-yazi is one step closer to fitting Yazi into my daily workflow.

If you also like Yazi’s speed, preview capabilities, and plugin system, but can’t quite let go of the directness of dual-pane file managers, give this fork a try.

Why a Fork, Not a Plugin

One more note: initially, I actually tried to build this using Yazi’s built-in plugin system. The plugin route would be friendlier to users and wouldn’t require rebasing against upstream every time, so by all accounts it should have been the preferred approach.

But once I actually started, I realized Yazi’s plugins are essentially Lua scripts running on top of a Rust state machine: they can draw UI and compose existing commands, but they can’t change the underlying data structures, and they can’t add new commands. The things I wanted — independent tabs per pane, one-key cross-pane copy/move, single/dual toggle, preview toggle inside dual mode, undo/redo — pretty much all required changes at that lower level. It wasn’t something a layout tweak could solve.

There are pure-plugin attempts out there, which take the approach of drawing the two existing tabs side by side. Visually it looks like dual-pane, but “switching panes” is really just switching tabs, cross-pane copy has to be simulated with “switch over → paste → switch back” (visible flicker), and you can’t have truly independent tabs on each side. It ends up feeling more like a “two-view viewer” than a real dual-pane file manager.

So in the end I went with the fork. The cost is keeping it in sync with upstream myself, but in exchange every interaction can be shaped exactly the way I want. For me, that trade-off is worth it.

Spec Only, No Code: Perhaps This Will Become a New Way to Release Software

2026-03-14T21:52:56+08:00

I recently came across openai/symphony, and my first reaction wasn’t “I want to try this implementation” — it was “this release approach is interesting.”

Because the first option in its README isn’t teaching you how to install the official implementation. Instead, it directs you to build your own based on SPEC.md. Of course, they also included an experimental Elixir reference implementation, but that’s listed as the second option. This ordering itself is telling: what OpenAI really wants to convey first may not be a specific piece of code, but the design of the system.

I think this is worth noting. As code agents become increasingly capable, the “release” of some software in the future may not necessarily require a complete source code package. Instead, it could start with a sufficiently clear spec, letting everyone implement it in their own preferred language and runtime environment. Code will still exist, but it’s starting to look more like an instance of the spec rather than the sole deliverable.

Why I Find This Interesting

Previously, when we saw an open source project, the default understanding was: the source code in the repository is the product itself, and documentation merely helps you understand and use it. Even if a project had protocols, language standards, or design documents, those were usually supporting players.

But Symphony felt different to me this time. Its README puts “Option 1. Make your own” front and center, pointing to that lengthy SPEC.md. This isn’t “if you’re interested, you can also check out the design docs” — it’s clearly positioning “implement it yourself based on this spec” as a first-class entry point.

This shift in posture is interesting because it implies a new premise: for some software, the act of “implementation” itself is becoming cheap — cheap enough that authors can now reasonably assume that readers don’t necessarily have to use the official code and can instead bring the author’s ideas into their own familiar tech stack.

Though admittedly, OpenAI also gets you to consume more tokens this way — killing two birds with one stone.

Why This Is Starting to Work Today

I think the core variable is that code agents have gotten stronger.

A few years ago, “just implement it yourself based on the spec” would have sounded more like a joke. Because no matter how clearly a spec was written, there was still a massive amount of mechanical, tedious implementation work between document and working code. Many people didn’t fail to understand the design — they simply didn’t have the energy to fully realize it.

But things are different now. Especially for a project like Symphony, whose core value isn’t some hard-to-replicate low-level algorithm, but rather a set of system boundary definitions and workflow designs: what’s the problem, what’s the goal, what are the core components, what’s the domain model, how are in-repo contracts like WORKFLOW.md organized, how is configuration parsed, how do the agent runner and issue tracker coordinate. Once these things are written into a spec, the essential “structural skeleton” has been laid out.

The remaining code is often more like translating that skeleton into a particular language and engineering style. And “translation” is precisely what code agents are getting increasingly good at.

This Is Different from Traditional “Standards”

Of course, “spec first, implementation second” isn’t a new concept. Protocols, language standards, file format standards have always existed. But what I think is different this time is that it’s not a mature ecosystem slowly distilling a standards document after years of evolution.

It’s more like treating the spec as the primary deliverable from the very beginning.

And there’s an additional premise that wasn’t as strong before: the publisher can now reasonably assume that the reader has a capable enough coding agent nearby to quickly turn the spec into a working version. In other words, this spec isn’t just targeting patient human engineers who read documentation — it’s also targeting an implementation agent that can start working at any time.

This transforms “spec” from a static, archival document into a publication medium that can be directly executed upon.

What I Think Might Emerge

I’m increasingly feeling that a certain class of software projects may genuinely move toward this “spec-first” release approach.

That is, the core content an author publishes would become:

A sufficiently clear spec
A document describing system boundaries and constraints / workflow prompts
A set of tests or examples that can verify behavior
Perhaps a reference implementation, but it wouldn’t necessarily be the only implementation

Then on the user’s end, it’s no longer just “git clone and run it,” but rather “hand the spec to my own agent and let it generate a version in my preferred language, framework, and deployment approach.”

The benefits are significant.

First, different teams can more naturally align with their own tech stacks. Some want Elixir, some want Go, some want Rust, some just want to absorb the core ideas into their existing system — none of them need to be tightly bound to the official implementation.

Second, the author’s focus shifts from “this specific code” to “this design.” This way, a project’s influence can sometimes actually be greater, because what others adopt isn’t just a repository but the methodology behind it.

Third, for many tools in the agent era, the lifespan of a reference implementation may not matter as much as before. What truly endures may be the spec, the tests, and the workflow constraints; the actual code can be continually localized, rewritten, and replaced.

Of Course, This Doesn’t Suit All Software

That said, I don’t think this path works everywhere.

If a project’s core value lies in extremely detailed performance optimization, heavy engineering accumulation, or an interactive experience that’s hard to fully describe in text, then a spec alone clearly isn’t enough. There are also things like model weights, specific training results, and processed datasets that can’t simply be “given a spec and rebuilt.”

So the types of things most likely to go spec-first, I’d guess, are:

Orchestration / workflow tools
Protocol and service glue layers
Systems where enterprises really just want to implement the ideas, not necessarily stick to the official implementation
Infrastructure components that already emphasize contracts

Additionally, if specs are truly to become the primary deliverable, I think they’ll need to be paired with more supporting materials — conformance tests, standard example inputs and outputs, and even implementation hints for agents. Otherwise, no matter how long the spec is, different implementations will easily drift apart.

A Change I Find Quite Fresh

Linus Torvalds once said, “Talk is cheap, show me the code.” That quote might not hold as well today. Because now, “code is cheap.” As code agents mature, we may start seeing a different reality: the truly stable part isn’t necessarily a particular piece of source code, but the spec behind it.

Source code becomes a momentary projection of the spec — it can be implemented in this language, reimplemented in that one; organized this way today, rewritten with a different framework tomorrow. As long as the spec and behavioral constraints remain, what the author truly wanted to express is still there.

If things really develop in this direction, then the very act of “releasing software” may look quite different from today. What gets released wouldn’t just be code, but design, constraints, and a specification clear enough for an agent to continue producing code from.

I think this is quite interesting. Symphony is certainly far from the endpoint of this trend, and it still comes with a reference implementation. But at least it has brought something that previously didn’t look like a “formal release approach” very naturally to the forefront.

net-use Released: Monitor Which IPs a macOS App Actually Connects To

2026-03-13T14:52:52+08:00

Sometimes when setting up a firewall whitelist for an app, the hardest part isn’t configuring rules — it’s not knowing which addresses the app actually connects to. And many modern apps aren’t just a single main process; they spawn helpers, renderers, crash reporters, and other child processes, so monitoring a single PID often isn’t enough. So I wrote a small tool called net-use that tracks the remote IPs accessed by a specified app and its entire process tree in real time, outputting deduplicated results.

Repository: https://github.com/jtianling/net-use

In One Sentence

net-use is a network connection monitoring tool for macOS. It uses the proc_pidfdinfo system call to enumerate socket information, capturing TCP/UDP remote addresses accessed by a specified app and all its child processes in real time. To better suit the firewall whitelist use case, IPv4 addresses are aggregated to /24 subnets by default, while IPv6 addresses are kept in full.

Why I Built This

My need was simple: I wanted to know what addresses an app is actually accessing and compile the results into a whitelist I can use directly.

For a quick glance at network connections, there are plenty of tools that can get the job done. But once you need to pin it down to a specific app — especially a desktop app that spawns many child processes — things get complicated: processes change, PIDs change, connections appear dynamically, and you have to deduplicate manually. So I just built a dedicated tool for this.

Usage

Installation:

cargo install net-use

The simplest way is to launch TUI mode directly:

sudo net-use

After launching, you can browse installed apps, filter by typing, and press Enter to start monitoring. During monitoring, you can export to a file, copy to clipboard, toggle sort order, and switch between subnet-aggregated and raw IP display.

If you prefer not to use the interface, you can go straight to CLI:

# Monitor by Bundle ID
sudo net-use --bundle com.google.Chrome --no-tui

# Monitor by process name
sudo net-use --name curl --no-tui

# Monitor by PID
sudo net-use --pid 1234 --no-tui

Output is a deduplicated address list, for example:

250.80.0/24
217.14.0/24
f8b0:4004:800::200e

Ready to use directly as a whitelist.

A Few Other Useful Features

Can monitor apps that haven’t launched yet — starts collecting automatically once they start
Historical data persists after the app exits; data continues to accumulate when it reappears
Supports pause/resume monitoring
Supports persisting historical results to a file

Limitations

This tool currently only supports macOS and requires sudo, since reading process socket information requires elevated privileges.

It’s also polling-based, defaulting to once every 200ms, so extremely short-lived connections could theoretically be missed. Additionally, some XPC services launched via launchd may not fall entirely within the same process tree — that’s another current limitation.

In short, if you also have the need to know “which IPs an app is actually connecting to,” give it a try. For me at least, I finally don’t have to stare at Activity Monitor while manually compiling whitelists anymore.

skillsmgr Released

2026-02-03T00:00:00+08:00

While organizing skills for various AI coding tools recently, I realized each tool has its own directory and format, and switching between them gets confusing fast. So I built a unified management tool: skillsmgr. It installs skills centrally into ~/.skills-manager/ and deploys them to projects through a single .agents/skills/ directory, currently supporting 44 tools.

Repository: https://github.com/jtianling/skills-manager

In One Sentence

skillsmgr is a unified skills manager — install skills once into a local repository, then deploy them to any project or globally on demand, supporting 44 AI coding tools.

Highlights

Central repository, deploy anywhere — Skills are installed once into ~/.skills-manager/. After that, add lets you interactively pick from all locally installed skills and deploy them to any project or globally — no need to remember the original repo URL or path every time.
Custom groups for batch management — Organize your own skills into named groups (e.g., --group my-tools). Deploy an entire group to a project with a single add --group command, making it easy to maintain and share personal skill collections.
Zip archive support — Install skills directly from .zip files or Anthropic’s .skill packages, which makes it simple to package and share skill bundles outside of GitHub.

Deployment Model

project/
├── .agents/
│   └── skills/
│       ├── code-review -> ~/.skills-manager/official/anthropic/skills/code-review
│       └── example-skill -> ~/.skills-manager/custom/example-skill
├── .claude/
│   └── skills -> ../.agents/skills
└── .cursor/
    └── skills -> ../.agents/skills

All skills deploy to .agents/skills/. Native tools read that directory directly. Non-native tools use a symlink bridge to their legacy skill path. You can also use --copy to deploy project-local copies instead.

Installation

npx skillsmgr setup

Usage

# Install official Anthropic skills
npx skillsmgr install anthropic

# Install from a GitHub repository
npx skillsmgr install owner/repo

# Install from a local directory or zip archive
npx skillsmgr install ./my-skill
npx skillsmgr install ./skills-archive.zip

# Navigate to your project and deploy interactively
cd your-project
npx skillsmgr init

# Add a specific skill to a specific tool
npx skillsmgr add code-review -a claude-code

# Deploy globally
npx skillsmgr add code-review -g -a claude-code

# Inspect deployed skills
npx skillsmgr list --deployed

Supported Tools

Currently supports 44 AI coding tools. The interactive selector shows 16 major tools (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Cline, Windsurf, etc.), with 28 more available via the -a flag. Native tools read .agents/skills/ directly; non-native tools are bridged via symlinks.

Features

Unified management: all skills installed to ~/.skills-manager/, organized into official / community / custom categories
Multi-tool deployment: one set of skills deployed to multiple tools through a unified directory + symlink bridges
Symlinks by default: skill updates sync automatically; --copy mode also available
Custom groups: batch manage and deploy your own skill collections with --group
Interactive selector: supports search, group collapsing, and vim-style shortcuts
Global deployment: use -g to deploy to agent user-level directories

rulesmgr Released: One Set of Rules, Synced Across Multiple Tools

2026-02-03T00:00:00+08:00

While using AI coding tools like Claude Code, Cursor, and Cline recently, I kept running into the same tedious problem: each tool has its own rules directory with slightly different formats, and team conventions need to be copy-pasted across multiple locations, easily drifting apart over time. So I built a small tool called rulesmgr to manage a single set of rules and deploy them to multiple tools at once.

Repository: https://github.com/jtianling/rules-manager

In One Sentence

Maintain a single rule template, select your target tools, and it automatically generates the corresponding directory structure, with sync support in copy mode.

Installation

npx rulesmgr setup

This creates example rule templates in ~/.rules-manager/, with a structure like this:

~/.rules-manager/
├── 01-tech-stack.md
├── 02-coding-principles.md
├── 03-architecture.md
├── 04-testing.md
├── 05-git-commit.md
├── 06-code-review.md
└── languages/
    ├── typescript-coding-style.md
    ├── python-coding-style.md
    └── ...

Deploy to a Project

# Interactive mode
npx rulesmgr init

# Specify tools and language
npx rulesmgr init --tools=claude-code,cursor --lang=typescript

# Use copy mode
npx rulesmgr init --tools=claude-code --copy

# Deploy .gitignore
npx rulesmgr init --gitignore

Sync Rules in Copy Mode

npx rulesmgr sync

Supported Tools

Currently supports Claude Code, Cursor, Cline, Roo Code, Kilo Code, Windsurf, OpenCode, TRAE, Goose, Antigravity, and more. See the repository README for the full directory mapping.

Feel free to try it out and share feedback. More tools and templates will be added over time.

Ollama Rerank Adapter

2025-12-17T00:00:00+08:00

A lightweight HTTP service that wraps Ollama’s Rerank model into a standard Rerank API, enabling Dify and other applications to use local Ollama models for document reranking.

https://github.com/jtianling/dify-ollama-rerank-adapter

A Chrome Extension to Add Search to the DeepSeek Website

2025-12-08T00:00:00+08:00

DeepSeek is great to use, but the company has never paid much attention to improving the user experience. For example, the DeepSeek website has never had a search function for conversation history. So I built one. It’s not published on the Chrome Web Store — it’s open source, feel free to grab it.

https://github.com/jtianling/deepseek-search-chrome

A Programming Language Syntax Comparison Website

2025-12-02T00:00:00+08:00

I’ve always had to work with multiple programming languages simultaneously — either learning a new language while working on side projects, while also developing a company project, or writing both frontend and backend code in different languages within the same project. During these times, I always wished there was a website that could display syntax examples of the languages I’m using side by side, so my brain wouldn’t get mixed up when switching between them. After all these years, thanks to the maturity of large language models, building such a website has become incredibly easy. I’m posting the link here for anyone with the same need.

https://www.jtianling.com/programming-language-comparison