albertwujj/agent-term
A terminal for AI CLIs, expanded into a rich visual workspace for each session. Claude Code, Codex, Cursor CLI, and more. macOS and Windows/WSL. Extend it further and share your additions. - albert...
7 stars · 0 forks
README
AgentTerm
A terminal for AI CLIs, expanding each session into its own rich visual workspace for the new way of working (autoplays after loading):
View a frame: Tell apart 1 · Tell apart 2 · Resume · Comment · Docs 1 · Docs 2 · Docs 3 · Code 1 · Code 2 · Code 3 · Phone 1 · Phone 2. Dive deeper: Tell apart · Resume · Comment · Docs · Code · Phone.
Quick start: ask your agent. macOS, or Windows through WSL. Check first? Read the setup steps and what AgentTerm touches. Copy this prompt: Clone https://github.com/albertwujj/agent-term to ~/agent-term. Follow the recommended setup in its docs/setup.md for my current project, then launch AgentTerm there.
Phone access, including recording and transcription, and IDE integration have separate setup. Once a window opens, resume your previous session or start a new one, and work as usual. When you want to give precise feedback or ask a question, select and enter a comment.
Why expand the terminal If you are a terminal fan and want to get straight to it, skip ahead to what AgentTerm adds. The terminal is a natural home for coding agents: text in, text out, with the shell, git, and other tools one command away. Claude Code and Codex started there; Cursor and Copilot added CLIs alongside their IDE interfaces. An IDE or desktop app offers richer views and interactions than a text interface alone. Expanding the terminal lets AgentTerm add those capabilities while keeping your existing AI CLIs in the familiar text interface. As agents take on more implementation, traditional IDE functions take a back seat, and your energy and focus shift toward plans, reviews, and managing several sessions at once. The expanded terminal supports that work visually, like an IDE: plans and reviews render in the window, where you direct the agents right on the page. Richer views appear when needed, and the window returns to the terminal view when you finish. Persistent panels can compete with the session for your attention. Here the window is dedicated to your session, shaped by your work, and full screen if you like, with nothing else in view (one OS window per session).
Work on a document right in the terminal. The document area expands in full and closes as your focus shifts.
A vendor's desktop app moves the conversation out of the terminal and into an interface built around its own agent and workflow. With AgentTerm, you keep your choice of AI CLIs in the terminal's familiar text interface. Some terminals combine support for AI CLIs with an agent and platform of their own. AgentTerm's whole purpose is to make your existing AI CLIs work better for you. One OS window per session Why not tmux, or one manager app over every session? The OS already provides familiar, mature tools for arranging and switching windows: the taskbar, Dock, Mission Control, and alt-tab. Giving each session its own window and process lets AgentTerm build on those strengths and add what agent sessions need. Each session has a distinct visual signature to help you recognize it. To reduce clutter, AgentTerm hides sessions you don't need for a while; the session picker brings them back. A stable interface between agent and terminal This path can look hacky: the host parses text and reacts to it. Useful text conventions tend to persist, and in practice the patterns we rely on have held up well. We occasionally add support for new patterns, and those updates have been among the easier parts to maintain. It works from both sides: guide files instruct agents to print what the host understands, and the parser recognizes output styles agents already use. This integration does not require a vendor SDK or API. With a host that understands its agents, and agents that understand the host, an agent can use capabilities beyond those built into its CLI. For example, a plan the agent mentions can open inside the same window, rendered for you to read and write on. Through its protocol with the host, the agent treats what you write as intent and updates the plan in place.
Extend it further You and your agents can change and extend this terminal, down to its code, to fit your work and your team's. Use it and explore first; what you need may already be there. When you find something is indeed missing while you work, you are best placed to evaluate and fill the gap, with the scenario right in front of you. This terminal makes that quick: it is already a better tool for working with your agents, including the work to fix itself. Change its source, and every window opened afterward picks up your improvement. What's added so far Below are just examples. Follow the links to explore more features.
Plain terminal AgentTerm
Sessionshard to tell apart Each session has its own OS window, with a unique taskbar button or Dock tile (a preview on Windows, the session title on macOS), so you tell them apart at a glance.
Resumehard to find Type a few letters to find and resume a closed session; the picker searches your prompts and session titles to help you return to the session.
Commentmanually quote past output Select anything the agent prints and comment.
Docsappend-only, not rendered Ask for a plan as a markdown file and click its name. The doc opens rendered, and the rendered page is where you work: comment on any passage, or write in it directly; the agent replies in a thread on the passage, discusses your feedback when needed, and updates the document to reflect your intent. AgentTerm shows what you proposed and what the agent changed.
Codescrolling fragments, or a wall of diff The agent hands you a curated review, rendered, with a narrative you can follow and the parts that need your attention called out; you comment inline, it fixes and replies in place.
Phonenot connected, travel back to check See which agents need you across your machines. Open the same terminal on your phone, with the same layout so you recognize at once what you left behind; reply by voice.
Copyevery paste needs cleanup Copy what the agent wrote and it pastes into a chat or email ready to send, one clean paragraph instead of chopped lines. A doc in the viewer copies the same way.
Viewcan't click a file name to see it Click a file the agent mentions (a doc, an image, a video, a PDF) and see it right in the window, above your prompt; it gets out of the way as your focus shifts.
Shared checkout collisionstest ports, even with worktrees Type one @ mention (@proceed-b completes to the guide doc's path) and the agent takes the checkout lock and cuts a branch before its first edit; a padlock at the top right of each window shows who holds it.
Long jobsunresponsive, or a missed finish The agent starts a CI run or other long job and hands the terminal back; the job reports its own completion through the terminal and the idle agent is prompted to pick it up, even across a session restart; a runner icon at the top right shows what is running.
Not an IDEcan't jump from a cited symbol or line to the code Click any file:line or symbol the agent cites and your IDE jumps to that exact line after a brief pause for selection; Ctrl/Cmd-click jumps immediately. The editor stays read-only so a stray key changes nothing.
How it works AgentTerm runs your existing AI CLI in a full terminal, using Electron for the window, xterm.js for terminal emulation, and node-pty for the shell connection. The host parses terminal output for file references and recognized conventions, and keeps track of mentioned documents even when the CLI redraws the screen. Those references connect the conversation to host capabilities. A Markdown path identifies a document the host can render. A review:// reference can trigger validation, rendering, and automatic opening of a review. Document viewing and review build on this mechanism. Guide files tell agents how to follow these conventions. For example, agent-threads provides the guides and file protocol for document and review feedback. To keep the terminal responsive, repeated scans are combined and scheduled, while file checks and review rendering run asynchronously. Where to go next The quick start sets up the terminal together with plans, reviews, the checkout lock, long jobs, and the voice interpretation guide. Sessions started before you switched to AgentTerm work too. Follow the suite guides to start using them. For example, ask your agent for a curated review with @produce-r, which completes to produce-review.md. The agent curates and presents the changes for you to review and comment on. Add phone access when you want to continue remotely, or IDE integration if you use an IDE. These have separate setup; phone voice input also needs recording and transcription configured on the hub. Try a change with your agents. The next window you open picks it up, since every window starts from the latest source (how a window opens). MIT licensed. No telemetry, no account.