@agentmesh/agent

AgentMesh Agent Wrapper - Turn any AI coding assistant into a dispatchable, nudge-able agent.

Features

• Auto-register agents with AgentMesh HQ
• Background heartbeats to maintain online status
• Real-time nudges via WebSocket -> tmux send-keys
• Handoff notifications injected directly into agent session
• Works with any AI assistant: OpenCode, Claude Code, Cursor, etc.

Installation

Homebrew (macOS/Linux)

brew tap therajushahi/agentmesh
brew install agentmesh

npm

npm install -g @agentmeshhq/agent
# or
pnpm add -g @agentmeshhq/agent

Quick Start

1. Initialize Configuration

agentmesh init
# Prompts for:
#   - API Key (from agentmeshhq.dev/settings/api-keys)
#   - Workspace
#   - Default command (opencode, claude, etc.)

2. Start an Agent

agentmesh start --name backend-agent

# With options:
agentmesh start \
  --name backend-agent \
  --command "opencode" \
  --workdir ~/Dev/myproject \
  --model claude-sonnet-4

3. List Running Agents

agentmesh list

# Output:
# NAME             STATUS    SESSION                   PENDING
# backend-agent    online    agentmesh-backend-agent   1 handoff

4. Attach to Agent Session

agentmesh attach backend-agent
# Opens tmux session - see the AI working
# Detach with: Ctrl+B, D

5. Nudge an Agent

agentmesh nudge backend-agent "Check the failing CI tests"

6. Stop an Agent

agentmesh stop backend-agent

Configuration

Config is stored at ~/.agentmesh/config.json:

{
  "apiKey": "am_live_xxxx",
  "workspace": "agentmesh",
  "hubUrl": "https://agentmeshhq.dev",
  "defaults": {
    "command": "opencode",
    "model": "claude-sonnet-4"
  },
  "agents": []
}

How It Works

1. Start: Creates a tmux session running your AI assistant
2. Register: Registers the agent with AgentMesh HQ
3. Heartbeat: Sends heartbeats every 30s to maintain online status
4. WebSocket: Listens for real-time events (handoffs, nudges, blockers)
5. Inject: When events arrive, injects messages via tmux send-keys

The AI assistant sees the injected message as if you typed it, maintaining full conversation context.

Requirements

• tmux (must be installed and in PATH)
• Node.js 18+
• An AgentMesh HQ account with API key

Versioning

This package uses Semantic Versioning. Releases are fully automated — do not publish manually.

How to release

1. Update version in packages/agent/package.json on the dev branch (via PR).

2. Push a tag matching agent-v<version> from the commit where the version was bumped:

   # After your version-bump PR is merged to dev and pulled locally:
   git tag agent-v0.2.1 <merge-commit-sha>
   git push origin agent-v0.2.1

3. The publish-agent.yml GitHub Actions workflow triggers automatically and:

   • Builds and tests the package
   • Verifies package.json version matches the tag
   • Publishes to npm as @agentmeshhq/agent
   • Creates a GitHub Release
   • Updates the Homebrew formula in therajushahi/homebrew-agentmesh

Rules

• Never run npm publish manually. It bypasses the version check and can publish a mismatched version (e.g. a package.json that says 0.1.2 getting published as 0.2.0).
• Never skip a version number. The Homebrew formula uses the version string; if the npm registry already has a higher version, brew upgrade will not install the new formula.
• The tag drives everything. The tag name (agent-v0.2.1) is the source of truth — the workflow validates that package.json matches before publishing.
• All work targets dev. main is for releases only, managed by the Product Owner. PRs must target dev.

Version history incident

In Feb 2026, 0.2.0 was published manually with npm publish from a commit whose package.json said 0.1.2. This caused:

• npm registry to have 0.2.0 as the latest version
• The Homebrew formula to point at 0.2.0
• All subsequent CI-published versions (0.1.3, 0.1.4) to be lower than 0.2.0, so brew upgrade ignored them
• Workers already on 0.2.0 unable to receive fixes

The fix was to bump past 0.2.0 → 0.2.1 using the correct automated pipeline.

March 2026: v0.3.0 manual publish (same mistake repeated)

Published 0.3.0 manually via npm publish during E2E verification of PR #304 (unique workdirs + deploy key cloning). The brew formula was also updated manually with an incorrect tarball URL (agentmeshhq-agent-0.3.0.tgz → 404; correct is agent-0.3.0.tgz). Additional issues found: deploy key credential inactive, orphaned GitHub deploy key, missing repo_id on agent assignments, FK violation on HQ deploy-key endpoint.

Fix: Corrected brew formula URL + SHA. Tagged agent-v0.3.0 retroactively. Full post-mortem in ~/Dev/infra-docs/agent-release-ops.md.

License

MIT