Skip to content
Back to search

agent-rail

MarketplaceWorks with Claude CodeGitHub

Local marketplace for the agent-rail plugin

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zenonix-studio--agent-rail/badge.svg)](/listings/zenonix-studio--agent-rail)

HTML

<a href="/listings/zenonix-studio--agent-rail"><img src="/api/listings/zenonix-studio--agent-rail/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "agent-rail",
  3. "description": "Local marketplace for the agent-rail plugin",
  4. "owner": {
  5. "name": "Zenonix Studio"
  6. },
  7. "plugins": [
  8. {
  9. "name": "agent-rail",
  10. "source": "./",
  11. "description": "Per-session progress rail for Claude Code, written to ~/.agent-rail/sessions/"
  12. }
  13. ]
  14. }
README.md · README · 219 lines · 1 finding marked
  1. # agent-rail
  2. A live rail for your Claude Code and Codex jobs: progress, milestones and the agents behind them.
  3. <p align="center"><img src="docs/images/menubar.png" width="454" alt="The AgentRail menubar popover: three jobs with their steps, the current step's activity and the agents running under them"></p>
  4. ## Claude Code
  5. Needs Node 18 or later on PATH. In Claude Code (terminal or desktop app):
  6. ```
  7. /plugin marketplace add Zenonix-Studio/agent-rail
  8. /plugin install agent-rail@agent-rail
  9. ```
  10. Restart Claude Code. Both the desktop app and the terminal get an **Agent rail** pane beside the chat, opened when a session starts (`/rail` toggles it; a `/config` switch keeps it closed, see [What runs on its own](#what-runs-on-its-own-and-how-to-turn-it-off)), plus `/agent-rail:history` and, if you add it, the status line below.
  11. The rail starts in **free** mode, which only watches. To have the agents report a plan and progress notes, open `/config` and set agent-rail's **Mode** to `railed` (see [Modes](#modes-free-and-railed)).
  12. <p align="center">
  13. <img src="docs/images/claude-desktop.png" width="430" alt="The Agent rail pane in the Claude desktop app: a finished job with four stage-colored steps and their durations, the Explore agent with its own steps, and the closing summary">
  14. <img src="docs/images/claude-cli.png" width="430" alt="The Agent rail pane in the Claude Code terminal: the job at 25 percent, the current step, a running Explore agent with its own steps, and the latest progress note">
  15. </p>
  16. <p align="center"><sub>The pane in the desktop app (left) and in the terminal (right)</sub></p>
  17. ## Modes: free and railed
  18. The rail has two modes. **Free** is the default; pick one in `/config` under agent-rail's **Mode** (see [Switching](#switching) below).
  19. **Free: watch only.** The plugin adds nothing to the conversation. It builds the rail from what the agents already do: each tool call becomes a step, its stage inferred from the tool (reading and searching is `analyse`, editing is `dev`, an edit after a failing build or test is `fix`, builds and tests are `review`), and agent rows show each subagent's own calls.
  20. - You watch the agents as they would work without the plugin.
  21. - Nothing for the agent to follow.
  22. - The rail shows the steps already taken, not the ones still to come, so a job has no percentage. The title is the start of your prompt. In the desktop app, Claude's own plan still gives the full step list.
  23. **Railed: the agents report to the rail.** The plugin's prompt hook asks the agent to start each new task with a `rail: <title> — <summary>` line, to lay out a 3–7 step plan with a stage on each step (`plan:`, `analyse:`, `dev:`, `fix:`, `review:`) and to add a one-sentence progress note as it goes. In the Claude desktop app and in Codex the plan goes in the agent's task list; in the Claude Code terminal, in a task list it already keeps, else in `plan:` and `step:` lines in its reply, so no extra tool calls are needed. Subagents write the same lines.
  24. - A short title and summary written for the task.
  25. - The whole plan up front: steps still to come, `2/4` and a percentage.
  26. - Stages chosen by the agent, and progress notes in plain words.
  27. - It adds a few lines to what the agent writes, so it is not the untouched flow. If you already keep your own task list or plan files, the two can overlap.
  28. **Which one.** Railed helps the person watching, not the agent. In our tests (Claude Opus, 20 runs of two coding tasks scored by hidden checks) both modes scored the same every time. What railed adds is the view: you see the plan in the first minute and can stop a wrong one early, and you know how much is left. Use railed when you follow long jobs live; keep free when you let jobs run on their own, or want the agents untouched.
  29. ### Switching
  30. In Claude Code (terminal and desktop app), pick the mode in the plugin's settings: `/config`, then agent-rail's **Mode**, `free` or `railed` (the menubar app's gear menu has the same switch as **Railed mode**). It is stored in `~/.claude/settings.json`:
  31. ```json
  32. {
  33. "pluginConfigs": { "agent-rail@agent-rail": { "options": { "mode": "railed" } } }
  34. }
  35. ```
  36. Codex's hooks read the same setting, so with Claude Code installed one switch covers both. Without Claude Code, or to override the setting, set the `AGENT_RAIL_MODE` environment variable: `"env": { "AGENT_RAIL_MODE": "railed" }` in `~/.claude/settings.json`, or in the shell that starts Codex: `AGENT_RAIL_MODE=railed codex`. When set, it wins over the setting. Restart Claude Code or Codex after changing it.
  37. ## Menubar app
  38. A native macOS menubar app that shows your running jobs. It reads the session files in `~/.agent-rail/sessions/*.json`.
  39. - Local: it never writes to the state folder and sends nothing over the network.
  40. - English and Turkish, following the system language.
  41. - Settings (gear icon at the bottom): **Notifications** and **Open at login**. Open at login is off until you turn it on, and matches System Settings → General → Login Items. With the Claude Code plugin installed, the same menu also has the plugin's `/config` switches (**Railed mode**, **Open the pane at start**, **Rail above the prompt**). Both read and write `~/.claude/settings.json`, so a change in one shows in the other.
  42. - A card with no activity can be hidden (**Hide**), or its session stopped (**Stop session…**, right-click or under the expanded card). Stopping ends the whole Claude Code or Codex session and its agents, after a confirmation; it is offered only while the process the hooks last ran under is still that one (same pid and start time).
  43. **Install:** download `AgentRail-<version>.dmg` from [Releases](https://github.com/Zenonix-Studio/agent-rail/releases), open it and drag AgentRail into Applications. It runs in the menubar (no Dock icon) and needs macOS 14 or later. Allow notifications when it asks, to hear when a job is done, needs you or is failing.
  44. <details>
  45. <summary>Build from source</summary>
  46. Requirements: macOS 14+ and Xcode 26.
  47. ```sh
  48. xcodebuild -project menubar/AgentRail.xcodeproj -scheme AgentRail \
  49. -destination 'platform=macOS' -derivedDataPath menubar/build build
  50. ```
  51. Install it to get notifications (job done, needs you, failing). macOS only asks for notification permission for an app in an Applications folder; run from `menubar/build`, the request is denied without a prompt. Sign it with your own development team:
  52. ```sh
  53. xcodebuild -project menubar/AgentRail.xcodeproj -scheme AgentRail \
  54. -destination 'platform=macOS' -derivedDataPath menubar/build build \
  55. DEVELOPMENT_TEAM=<your team id> CODE_SIGN_STYLE=Automatic CODE_SIGN_IDENTITY="Apple Development"
  56. cp -R menubar/build/Build/Products/Debug/AgentRail.app ~/Applications/
  57. open ~/Applications/AgentRail.app
  58. ```
  59. If a denied prompt was recorded earlier, turn AgentRail on in System Settings > Notifications. `AgentRail.app/Contents/MacOS/AgentRail --notify-test` (via `open --args`) prints the permission state and posts a test notification.
  60. Run against the sample state (written to a temp dir, so the working tree stays clean; quit any running copy first, since `open -n` starts a second instance):
  61. ```sh
  62. node scripts/sample-state.mjs /tmp/agent-rail-sample
  63. open -n --env AGENT_RAIL_HOME=/tmp/agent-rail-sample \
  64. menubar/build/Build/Products/Debug/AgentRail.app
  65. ```
  66. The Xcode project is generated from `menubar/project.yml`. After changing it, regenerate with:
  67. ```sh
  68. cd menubar && xcodegen generate
  69. ```
  70. To pack a DMG: `scripts/release-menubar.sh --unsigned` for a local try, or with `DEVELOPER_ID` and `NOTARY_PROFILE` set for a signed, notarized one (the script prints the one-time setup).
  71. </details>
  72. ## Web viewer
  73. The same view in a browser, for Windows and Linux (it runs on macOS too). It reads the session files in `~/.agent-rail/sessions/*.json`, like the menubar app, so set up the [Claude Code plugin](#claude-code) or [Codex](#codex) first: they write those files.
  74. - Running jobs with their steps and agents, plus history, token stats and a legend of the stage colors.
  75. - **Hide** a quiet card, or **Stop session…** to end a Claude Code or Codex session and its agents, after a confirmation.
  76. - English and Turkish, following the browser language.
  77. - Local: it listens on `127.0.0.1` only and answers no other host name.
  78. **Windows: one command.** Open PowerShell (Start menu, type `powershell`) and paste:
  79. ```
  80. irm https://raw.githubusercontent.com/Zenonix-Studio/agent-rail/main/web/install.ps1 | iex
  81. ```
  82. It installs Node.js first if you don't have it (it asks, then uses winget), puts the viewer in `%LOCALAPPDATA%\agent-rail` and starts it. Then:
  83. - Click the agent-rail icon in the taskbar tray (it may be under the `^` arrow) to open it as a small window.
  84. - A notification tells you when a job is done, needs you or is failing, even with the window closed.
  85. - It starts with Windows and is in the Start menu as **agent-rail**. Right-click the tray icon to turn **Start with Windows** off or on, or to quit.
  86. - It runs in the background with no window. If a console window opens at sign-in (an install from before November 12), run the install command again to update; closing that window stops agent-rail.
  87. - To update, run the same command again. To remove it:
  88. ```
  89. & ([scriptblock]::Create((irm https://raw.githubusercontent.com/Zenonix-Studio/agent-rail/main/web/install.ps1))) -Uninstall
  90. ```
  91. **Run from source (any OS, including Windows without the installer):** needs Node 18 or later and git.
  92. ```bash
  93. git clone https://github.com/Zenonix-Studio/agent-rail.git
  94. cd agent-rail
  95. node web/server.mjs
  96. ```
  97. Then open http://127.0.0.1:4317 (set `PORT` to use another port). It runs while that terminal stays open. To update, run `git pull` in the folder and start it again.
  98. ## History command
  99. `/agent-rail:history` lists the last 50 finished jobs across sessions, newest first, in the terminal and the desktop app. `/agent-rail:history <number>` shows one of them in full: its steps, agents and closing summary. The menubar's **Done today** button shows the same list. `/agent-rail:history stats`, the pane's **Stats** tab (`/rail stats`) and the menubar's chart button show the tokens spent since the weekly limit reset: the last 1, 3 and 5 days and the last 3, 10, 25 and 50 jobs.
  100. ## Codex
  101. Codex has no pane, so the rail opens in a terminal split beside it. Set it up once:
  102. ```bash
  103. git clone https://github.com/Zenonix-Studio/agent-rail ~/agent-rail
  104. node ~/agent-rail/scripts/install-codex.mjs
  105. ```
  106. Then, in a split beside Codex:
  107. ```bash
  108. node ~/agent-rail/bin/agent-rail-watch.mjs
  109. ```
  110. That is all: it follows the latest Codex session. As in the Claude pane, `n`, `h` and `s` switch between **Now**, **History** and **Stats**; `q` quits.
  111. <p align="center"><img src="docs/images/codex-terminal.png" width="600" alt="The live rail of a Codex job in a terminal: its summary, stage-colored steps and durations, the current step's activity and the latest progress note"></p>
  112. <details>
  113. <summary>More</summary>
  114. - Shortcut: the installer puts `rail` on PATH, the same command. Inside Codex, `$rail` opens it in a split in iTerm2, tmux, WezTerm or kitty (remote control on); elsewhere in a new Terminal window (the agent-rail hook opens it, outside the sandbox, so no approval is asked).
  115. - Add `claude` for the latest Claude Code session instead, an id prefix for one session, `--agents` to expand every agent row.
  116. - The installer adds the agent-rail hooks to `~/.codex/hooks.json` (backed up first, your own hooks kept), adds the `$rail` skill, and links `rail` into `~/.local/bin` (or the first writable folder of your PATH). Codex asks you to trust the new hooks on its next start.
  117. - Steps need Codex's `update_plan` tool. The installer asks before turning it on in `~/.codex/config.toml` (`--yes` turns it on, `--no-plan` skips the question; with no terminal to ask in, it skips). If your config already has a `[tools]` section it only prints the line to add yourself: `[tools.update_plan]` with `enabled = true`.
  118. - Codex jobs also show in the menubar, with their tokens (the main agent's and each subagent's).
  119. - Undo it all: `node ~/agent-rail/scripts/uninstall-codex.mjs`.
  120. </details>
  121. ## Status line
  122. `bin/agent-rail-statusline.mjs` prints one line for the current session's job in Claude Code's status line: stage, current step, progress, elapsed time, time left (once a step has finished) and running agents.
  123. ```
  124. ● dev · Editing parser.mjs · 3/5 · 2m10s · ~4m left · 2 agents
  125. ```
  126. Add it to your Claude Code settings (`~/.claude/settings.json`):
  127. ```json
  128. "statusLine": {"type": "command", "command": "node <path>/bin/agent-rail-statusline.mjs"}
  129. ```
  130. It prints nothing when the session has no job yet. Set `NO_COLOR` to drop the colors.
  131. ## What runs on its own, and how to turn it off
  132. | What | Default | To turn it off |
  133. |---|---|---|
  134. | The Agent rail pane opens when a Claude Code session starts | on | `/config` → agent-rail → **Open the pane at start** (or the menubar's gear menu): off. `/rail` still opens it. |
  135. | The current job is drawn above the prompt while the pane is not shown (terminal) | on | `/config` → agent-rail → **Rail above the prompt** (or the menubar's gear menu): off. |
  136. | The agents are asked for a title, a plan and progress notes | off (free mode) | `/config` → agent-rail → **Mode** (or the menubar's gear menu → **Railed mode**): `free`. See [Modes](#modes-free-and-railed). |
  137. | The hooks write a file per session to `~/.agent-rail` and delete files older than 30 days | on | Uninstall the plugin (`/plugin uninstall agent-rail@agent-rail`), then delete `~/.agent-rail`. See [Privacy](#privacy). |
  138. | The menubar app opens when you log in | off | Gear icon → **Open at login** turns it on or off (same as System Settings → General → Login Items). |
  139. | The menubar app notifies when a job is done, needs you or is failing | on, after you allow it | Gear icon → **Notifications**, or System Settings → Notifications → AgentRail. |
  140. | The Windows tray starts when you sign in | on | Right-click the tray icon → **Start with Windows**. Task Manager → Startup apps shows and changes the same setting; an update keeps your choice. |
  141. | The Windows tray shows notifications | on | Settings → System → Notifications → Windows PowerShell: off. |
  142. | The web viewer notifies in the browser | on, after you allow it | Untick **Notifications** at the bottom of the page. |
  143. The `/config` switches take effect in the next session.
  144. ## Privacy
  145. Everything stays on your machine; nothing is sent over the network. The hooks write one file per session to `~/.agent-rail/sessions/` (folder 0700, files 0600). Those files hold your prompts' text, job titles, step names, summaries, file names the agents touched and token counts. Files not written for 30 days are deleted. Collector errors go to `~/.agent-rail/collector.log`. Set `AGENT_RAIL_HOME` to keep them elsewhere.
  146. ## License
  147. MIT, see [LICENSE](LICENSE).
web/install.ps1 · Bundled script · 74 lines · 1 finding marked
  1. # Installs the agent-rail web viewer on Windows: Node.js if missing (via winget, after asking), the
  2. # viewer in %LOCALAPPDATA%\agent-rail\web, a Start menu and a startup shortcut, then starts the tray.
  3. # Install or update: irm https://raw.githubusercontent.com/Zenonix-Studio/agent-rail/main/web/install.ps1 | iex
    • Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
    • Line 3 on GitHub
  4. # Uninstall: & ([scriptblock]::Create((irm https://raw.githubusercontent.com/Zenonix-Studio/agent-rail/main/web/install.ps1))) -Uninstall
  5. param([switch]$Uninstall)
  6. $ErrorActionPreference = 'Stop'
  7. $dir = Join-Path $env:LOCALAPPDATA 'agent-rail'
  8. $web = Join-Path $dir 'web'
  9. $startMenuLink = Join-Path ([Environment]::GetFolderPath('Programs')) 'agent-rail.lnk'
  10. $startupLink = Join-Path ([Environment]::GetFolderPath('Startup')) 'agent-rail.lnk'
  11. $links = @($startMenuLink, $startupLink)
  12. # Start with Windows is on for a first install only: an update keeps what the tray menu or Task Manager set.
  13. $firstInstall = -not (Test-Path $dir)
  14. # A running tray and its server, found by our install path in their command lines (an update replaces their files).
  15. Get-CimInstance Win32_Process -Filter "Name='powershell.exe' OR Name='node.exe'" |
  16. Where-Object { $_.CommandLine -like "*$web*" } |
  17. ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
  18. if ($Uninstall) {
  19. foreach ($l in $links) { Remove-Item $l -Force -ErrorAction SilentlyContinue }
  20. Remove-Item $dir -Recurse -Force -ErrorAction SilentlyContinue
  21. Write-Host 'agent-rail web viewer removed.'
  22. return
  23. }
  24. function Get-NodeMajor {
  25. if (-not (Get-Command node -ErrorAction SilentlyContinue)) { return 0 }
  26. return [int](node -p "process.versions.node.split('.')[0]")
  27. }
  28. if ((Get-NodeMajor) -lt 18) {
  29. if (Get-Command winget -ErrorAction SilentlyContinue) {
  30. $answer = Read-Host 'agent-rail needs Node.js 18 or later. Install Node.js LTS with winget now? [Y/n]'
  31. if ($answer -notmatch '^[nN]') {
  32. winget install -e --id OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements
  33. $env:Path = [Environment]::GetEnvironmentVariable('Path', 'Machine') + ';' + [Environment]::GetEnvironmentVariable('Path', 'User')
  34. }
  35. }
  36. if ((Get-NodeMajor) -lt 18) { throw 'agent-rail needs Node.js 18 or later: install it from https://nodejs.org, then run this command again.' }
  37. }
  38. Write-Host 'Downloading agent-rail...'
  39. $zip = Join-Path $env:TEMP 'agent-rail.zip'
  40. $tmp = Join-Path $env:TEMP "agent-rail-$(Get-Random)"
  41. Invoke-WebRequest 'https://github.com/Zenonix-Studio/agent-rail/archive/refs/heads/main.zip' -OutFile $zip -UseBasicParsing
  42. Expand-Archive $zip $tmp -Force
  43. Remove-Item $web -Recurse -Force -ErrorAction SilentlyContinue
  44. New-Item -ItemType Directory $dir -Force | Out-Null
  45. Copy-Item (Join-Path $tmp 'agent-rail-main\web') $dir -Recurse
  46. Remove-Item $zip, $tmp -Recurse -Force -ErrorAction SilentlyContinue
  47. # The tray runs under Windows PowerShell (WinForms) from the Start menu and (first install) at sign-in,
  48. # through conhost --headless: with Windows Terminal as the default terminal, -WindowStyle Hidden alone leaves a window.
  49. $conhost = Join-Path $env:SystemRoot 'System32\conhost.exe'
  50. $ps = Join-Path $env:SystemRoot 'System32\WindowsPowerShell\v1.0\powershell.exe'
  51. $arguments = "--headless `"$ps`" -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File `"$web\tray.ps1`""
  52. $shell = New-Object -ComObject WScript.Shell
  53. # An existing startup shortcut is rewritten too, so older installs lose their window; a removed one stays removed.
  54. foreach ($l in @($startMenuLink) + @($startupLink | Where-Object { $firstInstall -or (Test-Path $_) })) {
  55. $s = $shell.CreateShortcut($l)
  56. $s.TargetPath = $conhost
  57. $s.Arguments = $arguments
  58. $s.WorkingDirectory = $web
  59. $s.Description = 'agent-rail: a live view of your Claude Code and Codex jobs'
  60. $s.Save()
  61. }
  62. Start-Process $conhost -ArgumentList $arguments -WindowStyle Hidden
  63. Write-Host ''
  64. Write-Host 'agent-rail is running. Click its icon in the taskbar tray (it may be under the ^ arrow) to open it.'
  65. Write-Host 'It is in the Start menu as "agent-rail". Right-click the tray icon to turn "Start with Windows" on or off.'
  66. Write-Host 'Run the same command again to update.'

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.