HydraCode

A visual desktop client for coding agents.

HydraCode presents each agent session as a live graph of inputs, outputs, tool calls, sources, files, and subagents. A desktop window represents one OpenCode project, and its active sessions are stacked vertically so they can be observed together across local checkouts and sandboxes.

Run both the desktop app and download site with Hydraterm, or start either package directly:

bun install
cd packages/desktop
bun run dev

The static download site is in packages/web and runs with bun run dev from that directory.

HydraCode stores its settings and themes under $XDG_CONFIG_HOME/hydracode. When XDG_CONFIG_HOME is not set, it uses ~/.config/hydracode.

On first launch it creates:

hydracode/
 settings.json
 themes/
 hydracode-light.json

settings.json selects a theme by ID:

{
 "theme": "hydracode-light"
}

Theme ID hydracode-light resolves to themes/hydracode-light.json. Theme IDs may contain lowercase letters, numbers, and hyphens. Theme files use a deliberately small shared token set:

• Colors: background, surfaces, text, border, accent, statuses, and graph relationships.
• Radii: small, medium, large, and round.
• Shadows: subtle, raised, and focus.
• Typography: UI and monospace font families.
• Diff: light/dark syntax mode plus foreground, background, gutter, separator, addition, and deletion colors.
• Layout: horizontal and vertical node distance.

The optional diff group controls patch rendering. Existing themes that omit it use HydraCode's readable light defaults. Set themeType to dark when supplying colors intended for dark syntax highlighting; this keeps Pierre's syntax tokens and the configured diff background in the same mode.

Restart HydraCode after changing the selection or a theme file.

cd packages/desktop
bun run lint
bun run test
bun run build

The first supported release target is macOS on Apple Silicon. HydraCode connects to the user's OpenCode V2 service and starts the installed opencode2 executable when no service is available. OpenCode can be installed from HydraCode Settings using its official installer.

Build an unsigned, unpacked application locally:

cd packages/desktop
bun run build

Build the signed and notarized DMG, update ZIP, and update metadata for release:

cd packages/desktop
bun run release

The packaged updater checks GitHub Releases on startup and every ten minutes. It downloads an available update in the background and waits for the user to click the header button before restarting and installing it. Updates are disabled in development builds.

The release workflow runs for tags matching v*. The tag must equal the packages/desktop/package.json version, for example v0.1.0. It requires these GitHub Actions secrets:

• APPLE_CERTIFICATE: base64-encoded Developer ID Application certificate.
• APPLE_CERTIFICATE_PASSWORD: password for the certificate archive.
• APPLE_API_KEY_CONTENT: App Store Connect API private key contents.
• APPLE_API_KEY_ID: App Store Connect API key ID.
• APPLE_API_ISSUER: App Store Connect API issuer ID.

The workflow signs and notarizes HydraCode, creates a GitHub Release, and uploads the DMG, ZIP, blockmap, and latest-mac.yml metadata used by electron-updater.

Before the first release:

1. Create a Developer ID Application certificate in the Apple Developer account, export it as a password-protected P12, and add its base64 encoding and password as APPLE_CERTIFICATE and APPLE_CERTIFICATE_PASSWORD.
2. Create an App Store Connect API key, then add its P8 contents, key ID, and issuer ID as APPLE_API_KEY_CONTENT, APPLE_API_KEY_ID, and APPLE_API_ISSUER.
3. Ensure the release commit, including the intended packages/desktop/package.json version, is pushed to main.
4. Run bun run lint:check, bun run test, and bun run build from packages/desktop at that commit.
5. Create and push the matching tag. This immediately triggers the public release workflow:

git tag -a v0.1.0 -m "HydraCode v0.1.0"
git push origin v0.1.0

The workflow keeps the GitHub Release as a draft until every asset has uploaded successfully.

Runtime selection and dependencies already cover macOS, Windows, and Linux on ARM64 and x64. Each future platform must build on its native runner so only the matching optional OpenCode package is installed and embedded.

When multiple architectures are published for one platform, their generated latest*.yml files must be merged so the update feed contains every architecture-specific artifact.