OpenHands Workspace Agent

This repository contains a local control plane for running an autonomous Hermes Agent (HA) + OpenHands Agent (OHA) workflow across one workspace.

The main flow is:

1. HA receives or normalizes a task specification.
2. HA invokes OHA through bin/workspace-agent.
3. OHA makes repository changes on an agent branch.
4. workspace-agent commits the work, opens a pull request, watches required checks, reacts to CI/review blockers, and merges the PR once the merge gates pass.

This first shareable version intentionally keeps the working local scripts mostly as-is. Local machine paths and model choices belong in config/config.json, which is ignored by git. Future portability work can make the scripts derive more paths dynamically.

What Is Tracked

The reusable source is intended to be:

• bin/ - command-line wrappers and supervisors
• prompts/ - HA/OHA prompt templates
• docker/ - optional sandbox support files
• templates/ - repo bootstrap template area
• config/config.example.json - copyable configuration template
• README.md and .gitignore

Local run data, project-specific tasks, secrets, and state are intentionally not tracked.

Requirements

Install the tools used by your chosen flow:

• Git and GitHub CLI (gh)
• Python 3
• OpenHands CLI
• Hermes CLI or compatible wrapper scripts
• Docker, if using the sandbox helpers
• The package managers needed by target repos, such as pnpm, Bun, or Node.js
• An LLM provider, for example DeepSeek via API key or a local Ollama/LiteLLM compatible endpoint

The target repositories should already be cloned under the configured workspace_root.

Setup

Clone this repository, then create local environment and config files:

cp .env.example .env
cp config/config.example.json config/config.json

Edit .env for your machine:

• OPENHANDS_AGENT_ROOT: this repository checkout
• WORKSPACE_AGENT_USER_HOME: your home directory
• WORKSPACE_AGENT_WORKSPACE_ROOT: the directory that contains your workspaces
• WORKSPACE_AGENT_PROJECTS_ROOT: the directory that contains target repos
• WORKSPACE_AGENT_SECRETS_PATH: local secrets file path
• WORKSPACE_AGENT_PATH: tool path prefix for wrappers
• HERMES_*: Hermes binary and home locations

Edit config/config.json for your workflow:

• workspace_root: usually ${WORKSPACE_AGENT_PROJECTS_ROOT}
• reference_repo: repo used as the source for bootstrap files
• hermes_system, hermes_sandbox, and hermes_system_home: usually ${HERMES_SYSTEM_BIN}, ${HERMES_SANDBOX_BIN}, and ${HERMES_SYSTEM_HOME}
• llm_profiles: model names, base URLs, and API-key environment variable names
• required_checks: exact GitHub check names required before merge
• repo_labels and repo_variables: labels and repo variables managed by the agent workflow

Secrets should come from environment variables or a local secrets file. Do not commit secrets. The current scripts look for:

the path configured by `WORKSPACE_AGENT_SECRETS_PATH`

Example:

DEEPSEEK_API_KEY=replace-with-your-key

Then run:

bin/workspace-agent doctor --repo <repo-name>

Usage

Run a single HA-supervised task:

bin/hermes-agentic doctor
bin/hermes-agentic run --repo <repo-name> --task /path/to/task.md

Run prepared OHA specs directly:

bin/workspace-agent doctor --repo <repo-name>
bin/workspace-agent run --repo <repo-name> --specs /path/to/specs
bin/workspace-agent status
bin/workspace-agent resume

Generate normalized specs from a planning document or directory:

bin/hermes-workspace-agent /path/to/repo/docs/or/plan
bin/hermes-workspace-agent /path/to/repo/docs/or/plan --execute

Without --execute, Hermes prints the workspace-agent run ... command. With --execute, it immediately hands generated specs to workspace-agent.

Runtime Data

When the system runs, it creates local work data in ignored folders:

• logs/ - OHA logs, prompts, failure bundles, and temporary PR bodies
• state/ - workspace-agent run ledger
• hermes-runs/ - legacy Hermes orchestration outputs
• hermes-agentic-runs/ - HA supervisor prompts and run output
• hermes-agentic-launch-logs/ - detached launch logs and dashboard logs
• sandbox-runs/ - sandbox task payloads and run metadata
• sandbox-logs/ - sandbox container logs
• tasks/ - local task prompts for specific projects
• test-inputs/ - local smoke-test fixtures

These folders are deliberately ignored. They can be archived or deleted without changing the shareable source code, although deleting state/ removes local run history for resume/status commands.

Safety Notes

• workspace-agent refuses to start work in a dirty target repo.
• OHA is instructed to work only inside the selected repository.
• Supervised failures write structured fail.json bundles in logs/.
• Merge is guarded by configured GitHub checks and the agent:auto-merge label.
• Keep config/config.json, .env files, run logs, task prompts, and state out of git unless you have reviewed them for private project data.

Publishing

This repo is prepared for a local initial commit first. Create and push a GitHub remote only after reviewing the staged files:

git status --short --ignored
git ls-files

No remote is configured by default.