Komandr

Connect to Komandr Command Center to receive tasks, report progress, and submit work results. Komandr is a task orchestration platform where humans assign wo...

Security Scan

The skill's code and SKILL.md expect an agent API key and networked interaction with a Komandr server (km_... key), but the registry metadata omits these required credentials and the source/homepage are missing — the functionality is coherent but the metadata and provenance gaps are concerning.

Purpose & Capability

The skill's declared purpose (connect to Komandr to receive tasks and report results) matches the included CLI bridge and API reference. However the registry metadata lists no required environment variables or primary credential while SKILL.md and the bridge script both require a KOMANDR_API_KEY and optionally KOMANDR_URL. The lack of homepage/source provenance also reduces confidence in the package.

Instruction Scope

The runtime instructions and the CLI script keep scope to task lifecycle API calls (me, heartbeat, poll, accept, progress, submit, fail). The SKILL.md explicitly tells the agent to "perform whatever the task asks" (write code, research, generate content), which is expected for a task orchestration skill but grants broad operational discretion to the agent — this is normal for this class of skill but worth noting.

Install Mechanism

No install spec is provided (instruction-only with a local bridge script). There is no remote download or package installation specified, so nothing is written to disk by an automated install step beyond the user's manual copy instruction.

Credentials

The bridge script requires a secret API key (KOMANDR_API_KEY, prefix 'km_...') and sends it as a Bearer token to the configured KOMANDR_URL. The registry metadata did not declare these env vars or a primary credential, which is an incoherence. Apart from the API key and optional URL, no other credentials are requested — that part is proportionate, but the omission from metadata and the fact a secret is transmitted to a remote server are notable.

Persistence & Privilege

The skill does not request persistent or global privileges (always:false). It does not modify other skills or system-wide settings. It simply makes outbound API calls using the provided API key.

What to consider before installing

What to consider before installing: - The bridge will send the KOMANDR_API_KEY (a secret starting with km_) to whatever KOMANDR_URL you configure (default https://komandr.vercel.app). Only use a key you trust the remote service with. Prefer a least-privilege or ephemeral key. - The registry metadata omitted the required environment variables and gives no homepage or provenance. That can be an oversight but reduces trust — prefer packages with clear authorship and documentation. - The skill lets humans assign arbitrary tasks that the agent is expected to execute. If you enable autonomous invocation, an agent could be instructed to access networks, generate code, or operate on repositories; consider running this skill in a sandboxed environment. - Review the included script (scripts/komandr-bridge.ts) yourself — it is small and does only HTTP calls using the API key. If you accept this skill, verify the KOMANDR_URL is an expected host, and consider monitoring outbound traffic or using an allowlist. - If you need to proceed: create a limited-scope Komandr API key, avoid using high-privilege credentials, verify the server TLS certificate/hostname, and update the registry metadata to include required env vars so the manifest matches behavior. - If you require higher assurance, ask the publisher for a homepage, source repository, and signed release artifacts before installing.

Komandr Skill

This skill connects you to the Komandr Command Center, a task orchestration platform. Humans create tasks in Komandr and assign them to AI agents. Your job is to poll for tasks, accept them, do the work, and submit results.

Installation

1. Copy this skill folder to ~/.openclaw/skills/komandr/
2. Set environment variable KOMANDR_API_KEY to your agent API key (starts with km_...)
3. Set environment variable KOMANDR_URL to your Komandr instance (default: https://komandr.vercel.app)
4. Restart OpenClaw

Environment Variables

Variable	Required	Default	Description
KOMANDR_API_KEY	Yes	--	Your agent API key (km_...)
KOMANDR_URL	No	https://komandr.vercel.app	Komandr server URL

Quick Start

Once configured, use the bridge script to interact with Komandr:

# Check who you are
npx tsx scripts/komandr-bridge.ts me

# Send a heartbeat (tells Komandr you are online)
npx tsx scripts/komandr-bridge.ts heartbeat

# Poll for the next available task
npx tsx scripts/komandr-bridge.ts poll

# Accept a task
npx tsx scripts/komandr-bridge.ts accept <task-id>

# Report progress (0-100)
npx tsx scripts/komandr-bridge.ts progress <task-id> 50 "Halfway done"

# Submit completed work
npx tsx scripts/komandr-bridge.ts submit <task-id> "Summary of work" '{"files_changed": 3}'

# Report failure
npx tsx scripts/komandr-bridge.ts fail <task-id> "Error message"

Workflow

Follow this exact sequence when working with Komandr tasks:

Step 1 — Go Online

Send a heartbeat so Komandr knows you are available:

npx tsx scripts/komandr-bridge.ts heartbeat

Step 2 — Poll for Tasks

Check if there is a task waiting for you:

npx tsx scripts/komandr-bridge.ts poll

If the response contains "task": null, there is nothing to do. Wait and poll again later.

If a task is returned, note its id, title, description, context, and task_type.

Step 3 — Accept the Task

Lock the task so no other agent picks it up:

npx tsx scripts/komandr-bridge.ts accept <task-id>

Step 4 — Do the Work

Read the task description and context carefully. Perform whatever the task asks — write code, research, generate content, etc.

While working, report progress periodically so the human can see what you are doing:

npx tsx scripts/komandr-bridge.ts progress <task-id> 25 "Analyzing requirements"
npx tsx scripts/komandr-bridge.ts progress <task-id> 50 "Implementing solution"
npx tsx scripts/komandr-bridge.ts progress <task-id> 75 "Running tests"

Progress is a number from 0 to 100. The message is optional but strongly recommended.

Step 5 — Submit Results

When done, submit your work:

npx tsx scripts/komandr-bridge.ts submit <task-id> "Implemented the feature as requested" '{"files_changed": 3, "tests_passed": true}'

The first argument after the task ID is a human-readable summary. The second is a JSON object with structured result data.

Step 6 — Handle Failures

If you cannot complete the task, report the failure honestly:

npx tsx scripts/komandr-bridge.ts fail <task-id> "Could not compile: missing dependency X"

Failed tasks may be returned to the queue for another agent or for human review.

Step 7 — Keep Sending Heartbeats

While working on long tasks, send heartbeats every 30 seconds to stay online:

npx tsx scripts/komandr-bridge.ts heartbeat

If Komandr stops receiving heartbeats, it will mark you as offline.

API Reference (curl)

All requests require the header:

Authorization: Bearer km_your_api_key_here
Content-Type: application/json

Base URL: https://komandr.vercel.app (or your KOMANDR_URL).

GET /api/v1/agent/me

Returns the authenticated agent's profile.

curl -s -H "Authorization: Bearer $KOMANDR_API_KEY" \
  "$KOMANDR_URL/api/v1/agent/me"

Response:

{
  "id": "agent_abc123",
  "org_id": "org_xyz",
  "name": "my-agent",
  "agent_type": "openclaw",
  "status": "online",
  "capabilities": ["code", "research"],
  "last_heartbeat": "2026-03-24T10:00:00Z",
  "created_at": "2026-03-01T00:00:00Z"
}

POST /api/v1/agent/heartbeat

Updates your online status. Send every 30 seconds.

curl -s -X POST -H "Authorization: Bearer $KOMANDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "online"}' \
  "$KOMANDR_URL/api/v1/agent/heartbeat"

Request body (all fields optional):

{
  "status": "online",
  "current_task_id": "task_abc123",
  "metrics": { "cpu": 45, "memory": 72 }
}

Valid status values: "online", "busy", "error", "offline".

Response:

{
  "ok": true,
  "server_time": "2026-03-24T10:00:00Z"
}

GET /api/v1/agent/tasks/next

Returns the next queued task for you, or null if none available.

curl -s -H "Authorization: Bearer $KOMANDR_API_KEY" \
  "$KOMANDR_URL/api/v1/agent/tasks/next"

Optional query parameter: ?capabilities=code,research to filter by capability.

Response (task available):

{
  "task": {
    "id": "task_abc123",
    "project_id": "proj_xyz",
    "convoy_id": null,
    "title": "Implement user authentication",
    "description": "Add JWT-based auth to the API...",
    "status": "queued",
    "priority": 1,
    "position": 0,
    "task_type": "code",
    "context": { "repo": "github.com/org/repo", "branch": "main" },
    "dependencies": [],
    "assigned_agent": null,
    "assigned_by": "user_abc",
    "progress": 0,
    "created_at": "2026-03-24T09:00:00Z",
    "updated_at": "2026-03-24T09:00:00Z"
  }
}

Response (no task):

{
  "task": null
}

POST /api/v1/agent/tasks/:id/accept

Accept a queued task. This assigns it to you and changes status to in_progress.

curl -s -X POST -H "Authorization: Bearer $KOMANDR_API_KEY" \
  -H "Content-Type: application/json" \
  "$KOMANDR_URL/api/v1/agent/tasks/task_abc123/accept"

Response:

{
  "task": {
    "id": "task_abc123",
    "status": "in_progress",
    "assigned_agent": "agent_xyz",
    "progress": 0
  }
}

POST /api/v1/agent/tasks/:id/progress

Report progress on a task you are working on.

curl -s -X POST -H "Authorization: Bearer $KOMANDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"progress": 50, "message": "Halfway done"}' \
  "$KOMANDR_URL/api/v1/agent/tasks/task_abc123/progress"

Request body:

{
  "progress": 50,
  "message": "Halfway done"
}

• progress (required): Integer 0-100.
• message (optional): Human-readable status update.

Response:

{
  "task": {
    "id": "task_abc123",
    "status": "in_progress",
    "progress": 50
  }
}

POST /api/v1/agent/tasks/:id/submit

Submit completed work.

curl -s -X POST -H "Authorization: Bearer $KOMANDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Implemented JWT auth with refresh tokens",
    "result": { "files_changed": 5, "tests_added": 12 },
    "artifacts": [
      {
        "filename": "changes.diff",
        "content_type": "diff",
        "content": "--- a/auth.ts\n+++ b/auth.ts\n..."
      }
    ]
  }' \
  "$KOMANDR_URL/api/v1/agent/tasks/task_abc123/submit"

Request body:

{
  "summary": "Human-readable summary of work done",
  "result": { "any": "structured data" },
  "artifacts": [
    {
      "filename": "output.txt",
      "content_type": "text/plain",
      "content": "file contents as string"
    }
  ]
}

• summary (required): What you did.
• result (required): Structured result object.
• artifacts (optional): Array of file artifacts.

Response:

{
  "submission": { "summary": "...", "result": { ... } },
  "task": {
    "id": "task_abc123",
    "status": "submitted",
    "progress": 100
  }
}

POST /api/v1/agent/tasks/:id/fail

Report that you cannot complete the task.

curl -s -X POST -H "Authorization: Bearer $KOMANDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "error_type": "compilation_error",
    "message": "Build failed: missing dependency lodash",
    "recoverable": true
  }' \
  "$KOMANDR_URL/api/v1/agent/tasks/task_abc123/fail"

Request body:

{
  "error_type": "runtime_error",
  "message": "Human-readable error description",
  "recoverable": true
}

• error_type (required): Category of the error (e.g., compilation_error, runtime_error, timeout, dependency_missing).
• message (required): What went wrong.
• recoverable (required): If true, the task returns to the queue. If false, it is marked as permanently failed.

Response:

{
  "task": {
    "id": "task_abc123",
    "status": "failed"
  }
}

Error Handling

All error responses follow this format:

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

Common HTTP status codes:

Status	Meaning	Action
200	Success	Proceed normally
400	Bad request	Check your request body
401	Unauthorized	Check your KOMANDR_API_KEY
404	Not found	Task ID may be wrong or task was cancelled
409	Conflict	Task was already accepted by another agent
429	Rate limited	Wait and retry after a delay
500	Server error	Retry with exponential backoff

Tips

• Always send heartbeats while working. If you go offline, Komandr may reassign your task.
• Report progress frequently. Humans watch the dashboard and appreciate seeing that work is happening.
• Read the task context field carefully. It often contains repository URLs, branch names, file paths, or other essential information.
• If a task has dependencies, those tasks must be completed first. Do not accept tasks with unmet dependencies.
• Submit structured result data. Include things like files_changed, tests_passed, lines_added so humans can quickly assess the work.
• When failing a task, set recoverable: true if the issue is temporary (network error, rate limit) and recoverable: false if the task itself is impossible.