@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 -> runtime session input
• 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 runtime 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": "openai/gpt-5.5"
  },
  "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": "openai/gpt-5.5" },
      "agents": []
    }
  }
}

Profile commands:

midfleet login --profile work --workspace midfleet
midfleet profile add midfleet1 \
  --hub-url https://dashboard.midfleet.io \
  --workspace usr_bbls-default \
  --api-key "$MIDFLEET_API_KEY"
midfleet profile list
midfleet profile show work
midfleet profile use work

Use a friendly profile name for each account, and store the workspace value that the key is actually scoped to. For example, a cofounder profile can be named midfleet1 while its saved workspace remains the canonical usr_bbls-default returned by the API.

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
midfleet --profile midfleet1 agents list --json
ssh dev-agent-hetzner 'midfleet --profile midfleet1 agents list --json'

Concurrent sessions on one machine

Config writes are serialized with an advisory lock and merge over the freshest on-disk profile, so parallel shells/agents cannot clobber each other's profiles. Two conventions keep this safe:

• Never rewrite a shared profile to point at a different environment. For local stack work, create a dedicated profile instead: midfleet profile add local-dev --hub-url https://hub.midfleet.local --workspace midfleet and invoke with --profile local-dev.
• Use --profile (or --workspace for one command) to isolate mutations instead of switching the active profile back and forth.

Epic Refinement

Use a participant login to run the governed Epic refinement lifecycle. References may be Midfleet issue IDs or linked GitHub issue references; the Hub resolves them authoritatively in the selected workspace.

midfleet --profile work --workspace usr_example epic refinement start Midfleet/midfleet#1703
midfleet --profile work --workspace usr_example epic refinement status https://github.com/Midfleet/midfleet/issues/1703
midfleet --profile work --workspace usr_example epic refinement accept Midfleet/midfleet#1703
# After remediating a blocked or failed launch:
midfleet --profile work --workspace usr_example epic refinement retry Midfleet/midfleet#1703

Add --json to any lifecycle command for the allowlisted epic-refinement-cli/v1 automation contract. These commands require the selected profile's participant session and never use API keys, agent tokens, or environment credentials as fallback authentication.

How It Works

1. Start: Creates a runtime 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 into the runtime session

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

Requirements

• 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