Skip to content

Group the agent commands under kcap agent #382

Closed

Description

@alexeyzimarev

The local-attach feature shipped its commands at the top level of the CLI:

kcap run-agent <vendor> [flags] [-- <agent args>]
kcap attach <agent-id>
kcap ls

Three problems follow from that shape:

  1. attach and ls are generic names occupying the top-level namespace. kcap ls says nothing about what it lists — a reader would guess sessions or repos before agents.
  2. They are undocumented in kcap --help. help-usage.txt has no entry for any of the three; the only place they appear is the README, so they are undiscoverable from the CLI.
  3. --name means the daemon name, not the agent name. Already confusing on kcap attach --name, and an outright trap on a stop subcommand.

There is also no way to stop a locally-started agent. The daemon only stops agents on a server-origin command, and that path explicitly refuses --private agents — so a kcap run-agent --private agent cannot be stopped from the CLI at all.

Proposal

One coherent group covering the whole lifecycle of a daemon-hosted agent:

kcap agent                                          # same as `kcap agent ls`
kcap agent start <vendor> [flags] [-- <agent args>]
kcap agent ls                    [--daemon <name>]
kcap agent attach <id>           [--daemon <name>]
kcap agent stop   <id>           [--daemon <name>]
kcap agent stop   --all [-y]     [--daemon <name>]

Plus: --name becomes --daemon, --detached becomes -d/--detach, and attach/stop accept any unique agent-id prefix.

This is a breaking change — the old spellings are removed, not aliased.

Activity

  1. linear-code commented on Jul 28, 2026

    @linear-code
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions