claudeers.
// Automation & Workflows

shoulder

Watch over your agents' shoulder. A TUI that shows Claude Code, Codex, Gemini CLI and opencode work in your project, live.

Actively maintained
100/100
last commit 21 days ago
last release 21 days ago
releases 5
open issues 0

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up shoulder (release-binary project) into my current project.
Found on https://claudeers.com/shoulder
Repo: https://github.com/bjarneo/shoulder
Homepage/docs: https://bjarneo.github.io/shoulder/
Detected install method: release-binary → inspect the README
Category: automation. Platforms: cli, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or install directly (release-binary)

Grab the latest release asset from GitHub.

# download a build from https://github.com/bjarneo/shoulder/releases
// or clone
git clone https://github.com/bjarneo/shoulder

// compatibility

Platformscli, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageGo

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

shoulder

Watch over your agents' shoulder.

See your coding agents work, live. shoulder follows Claude Code, Codex, Gemini CLI and opencode through your project. It shows the file that each agent reads or edits, the diff against your last commit, and the commands that it runs.

Claude simplifies snake.js one line at a time while Codex adds tests. shoulder follows both.

To see the 47-second demo, open the website or download shoulder-demo.mp4.

Install

Install shoulder with Go 1.26 or later:

go install github.com/bjarneo/shoulder@latest

Or download a binary from the latest release. There are binaries for linux-amd64, linux-arm64, darwin-amd64 and darwin-arm64:

curl -sL https://github.com/bjarneo/shoulder/releases/latest/download/shoulder-linux-amd64.tar.gz | tar xz
sudo mv shoulder-linux-amd64/shoulder /usr/local/bin/

To verify a download, compare it with checksums.txt in the release:

sha256sum -c checksums.txt --ignore-missing

With Nix, run shoulder from the flake, or enter a shell with Go and its tools for development:

nix run github:bjarneo/shoulder
nix develop

Run

Run shoulder in the project where your agents work:

cd ~/Code/myproject
shoulder

Then start your agents in the same project. Each agent shows up within a few seconds. To watch a different project, give its path:

shoulder ~/Code/myproject

shoulder watches the git top level of the directory. It shows the sessions that started there or in a subdirectory.

FlagDefaultDescription
--since1hShow sessions with activity in this period, for example 30m or 6h
--splitsoffStart with one split per agent
--signsoffShow changes as signs in the gutter, without the deleted lines
--versionPrint the version

Supported agents

shoulder reads the session logs that the agents already write. You do not configure the agents.

AgentSession dataTo use another location, set
Claude Code, with subagents~/.claude/projects/CLAUDE_CONFIG_DIR
Codex~/.codex/sessions/CODEX_HOME
Gemini CLI~/.gemini/tmp/GEMINI_CLI_HOME
opencode 2.x~/.local/share/opencode/opencode.dbXDG_DATA_HOME

shoulder only reads. It does not send input to an agent, it does not change files, and it does not connect to the network. It opens the opencode database read-only.

Screen

  • The left panel lists the agents and the changed files. A dot next to a file shows which agent is in that file now.
  • The center pane shows the file of the focused agent. A cursor and a label, such as ● A1 editing, show where the agent works.
  • In the inline diff, deleted lines show in red above the new lines. Added and changed lines have a green background. Press d to show the changes as signs in the gutter.
  • The terminal pane under the file shows the commands of the focused agent and their output.
  • The right panel shows the activity log of the focused agent: reads, searches, edits, commands, replies and prompts.
  • Press s for the split layout. Each agent gets a pane with its file and its activity log.

The bar under each agent shows how full its context window is.

Auto focus

Auto focus is on when shoulder starts. The view jumps to the work of the agents:

  • When an agent edits a file in the project, the focus goes to that agent and its file.
  • When the focused agent finishes, the focus goes to an agent that still works in the project.

shoulder waits at least 1.5 seconds between two jumps, so agents that work at the same time do not make the view flicker. In free scroll, the view does not jump.

To keep the focus on one agent, select it with 1 … 9, tab or a click. This pins the agent and turns auto focus off. To turn auto focus on again, press a. The status line shows auto or pinned.

Agent states

  • ● The agent runs a tool or writes a reply.
  • ○ The agent waits for you. It asked a question, or a tool call needs your approval.
  • ✓ The turn ended. The state is idle when the agent had no activity for 10 minutes.

Gemini CLI logs when a tool call waits for approval. For the other agents, shoulder assumes approval when a file tool has no result after 20 seconds.

Keys

KeyAction
1 … 9Pin an agent and follow it
tab, shift+tabPin the next or the previous agent
aTurn auto focus on or off
fToggle follow and free scroll
escGo back to follow
j, kMove the cursor
ctrl+d, ctrl+uMove half a page down or up
gg, GGo to the top or the bottom of the file
]c, [cGo to the next or the previous change
H, L, gT, gtOpen the previous or the next file tab
sToggle the follow layout and the split layout
dToggle the inline diff and the signs
RRead all sessions again
?Show all keys
qQuit

You can also click an agent, a file, a tab or a split pane.

Colors

shoulder uses the colors of your terminal theme. Text uses the default colors and the 16 ANSI colors, so it changes when you change the theme.

The panel shades and the line highlights are mixed from the colors that the terminal reports. shoulder asks the terminal again every 3 seconds, so a theme change shows while shoulder runs. If your terminal does not report its colors, the panels use the terminal background and the change signs show the diff.

In tmux, shades show correctly only when tmux supports true color. To turn it on, add set -as terminal-features ",*:RGB" to your tmux configuration.

Diff baseline

In a git repository, shoulder compares each file with HEAD. Outside git, it compares each file with the first content that it read.

Limits

  • shoulder reads opencode 2.x. It does not read the older part tables of opencode 1.x.
  • For Claude Code, Codex and opencode, the approval state is an estimate. See Agent states.
  • The binaries are for Linux and macOS. shoulder is not tested on Windows.

Develop

go test ./...
go build -o shoulder .

The code has three packages:

  • internal/watch reads the session logs of each agent and turns them into one event model.
  • internal/repo reads the project files and compares them with the last commit.
  • internal/ui draws the TUI with Bubble Tea.

To record the demo video again, run demo/record.py. The script header lists what it needs.

License

MIT. See LICENSE.

// faq

What is shoulder?

Watch over your agents' shoulder. A TUI that shows Claude Code, Codex, Gemini CLI and opencode work in your project, live.. It is open-source on GitHub.

Is shoulder free to use?

shoulder is open-source under the MIT license, so it is free to use.

What category does shoulder belong to?

shoulder is listed under automation in the Claudeers registry of Claude-compatible tools.

8 views
★ 76 stars
unclaimed
updated 23 days ago

// embed badge

shoulder on Claudeers
[![Claudeers](https://claudeers.com/api/badge/shoulder.svg)](https://claudeers.com/shoulder)

// retro hit counter

shoulder hit counter
[![Hits](https://claudeers.com/api/counter/shoulder.svg)](https://claudeers.com/shoulder)

// reviews

// guestbook

0/500

// related in Automation & Workflows

🔓

The agent that grows with you

// automationNousResearch/⟨Python⟩★ 264,763◷ MIT[ claude ]
🔓

The API to search, scrape, and interact with the web at scale. 🔥

// automationfirecrawl/⟨TypeScript⟩★ 199,533◷ AGPL-3.0[ claude ]
🔓

🌐 Make websites accessible for AI agents. Automate tasks online with ease.

// automationbrowser-use/⟨Python⟩★ 121,235◷ MIT[ claude ]
🔓

Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop

// automationLeonxlnx/⟨JavaScript⟩★ 110,676◷ MIT[ claude ]
→ see how shoulder connects across the ecosystem