Terminal

The Terminal tab opens a live shell session directly in the agent’s worktree directory. This is the most powerful debugging tool in Valdr — when an agent is stuck, failing tests, or producing unexpected output, you drop into the terminal and see exactly what the agent sees.

No context switching. No copying worktree paths. No hunting for the right branch. One click and you’re in the exact directory where the agent is working.

How it works

When you click the Terminal tab, Valdr opens a shell session with the working directory set to the agent’s worktree. The worktree path is displayed at the top of the terminal panel, confirming you’re in the correct location.

The terminal is a fully functional shell — you can run any command you would normally run in a terminal. It’s not sandboxed or restricted. You have the same access you’d have if you cd’d into the worktree yourself.

Treat it as a real local shell running with your user account’s permissions and environment. Use it on trusted machines and trusted workspaces only, and don’t assume it hides local credentials or configuration from the commands you run there.

What you can do

Inspect the agent’s work

git status           # See what the agent changed
git log --oneline    # Check the agent's commits
ls -la src/          # Browse the file structure
cat src/main.ts      # Read files the agent created or modified

Run tests

bun test             # Run the test suite
npm run lint         # Check for lint errors
cargo build          # Verify the code compiles

If the agent’s session failed because of test failures, running the tests yourself shows you the exact errors and lets you diagnose whether it’s a code issue, a test issue, or an environment issue.

Fix issues directly

vim src/config.ts    # Fix a typo or config issue
git add .            # Stage your fix
git commit -m "fix"  # Commit it

If the agent is still running (status: IDLE or RUNNING), you can fix an issue in the worktree and then use Reply to agent in the transcript tab to tell the agent to continue from the updated state.

Debug environment problems

node --version       # Check runtime versions
which bun            # Verify tool availability
env | grep PATH      # Check environment variables
cat .env             # Inspect environment configuration

Environment issues are a common cause of agent failures. The terminal lets you verify the environment matches what the agent needs.

When the Terminal tab appears

The Terminal tab is only available for sessions that have a worktree — typically task executor sessions. Orchestrator sessions don’t operate on code and won’t show the Terminal tab.

Sessions must have a valid worktree path in their metadata. If the worktree has been cleaned up (e.g., after a successful merge), the terminal will open but the directory may no longer exist.

Terminal vs SSH

You don’t need to SSH anywhere or set up remote access. The terminal runs locally because Valdr runs locally. The worktree is a directory on your machine, and commands execute with your local account’s permissions. The terminal is a convenience that saves you from manually navigating to the right path.

Workflow: diagnosing a stuck agent

Next steps

• Read the Transcript to understand what the agent was doing before you intervene.
• Check Worktree Diff to see what’s been changed so far.
• Review Metadata for session stats and model configuration.