@midfleet/agent

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

Features

• Auto-register agents with Midfleet
• 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 Midfleet/midfleet
brew install midfleet

npm

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

Quick Start

1. Initialize Configuration

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

2. Start an Agent

midfleet start --name backend-agent

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

3. List Running Agents

midfleet list

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

4. Attach to Agent Session

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

5. Nudge an Agent

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

6. Stop an Agent

midfleet stop backend-agent

Configuration

Config is stored at ~/.midfleet/config.json. During the rebrand, the CLI also reads the legacy ~/.agentmesh/config.json path for compatibility:

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

Newer configs are stored as named profiles so one machine can switch between accounts or workspaces without overwriting credentials:

{
  "version": 2,
  "activeProfile": "work",
  "profiles": {
    "work": {
      "apiKey": "mf_live_xxxx",
      "workspace": "midfleet",
      "hubUrl": "https://midfleet.io",
      "defaults": { "command": "opencode", "model": "claude-sonnet-4" },
      "agents": []
    }
  }
}

Profile commands:

midfleet login --profile work --workspace midfleet
midfleet profile list
midfleet profile show work
midfleet profile use work

For one-off commands, --profile selects a profile and --workspace temporarily overrides the workspace for that command without changing the saved profile:

midfleet status --profile work --workspace staging
midfleet config show --profile work --workspace staging
midfleet workspace list --profile work --workspace staging

How It Works

1. Start: Creates a tmux session running your AI assistant
2. Register: Registers the agent with Midfleet
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+
• A Midfleet account with workspace access

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. Run the publish workflow manually as a preflight from dev with the same version. Manual runs build, lint, test, smoke the CLI, run npm pack --dry-run, and perform a local package install smoke test (midfleet --version, --help, version --json, update-check --json) without publishing.

3. 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

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

   • Builds, lints, tests, and smoke-tests the package
   • Verifies package.json version matches the tag
   • Runs npm pack --dry-run
   • Preflight-only local package install smoke (for manual runs)
   • Publishes to npm as @midfleet/agent
   • Creates a GitHub Release
   • Updates the Homebrew formula in Midfleet/homebrew-midfleet after resolving the npm dist.tarball URL and verifying it uses the canonical https://registry.npmjs.org/@midfleet/agent/-/*.tgz path with no legacy agentmesh references. The formula includes midfleet --version, --help, version --json, and update-check --json smoke tests.

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 legacy tarball URL (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