# `ClaudeWrapper.Commands.Agents`
[🔗](https://github.com/genagent/claude_wrapper_ex/blob/main/lib/claude_wrapper/commands/agents.ex#L1)

`claude agents` command -- lists active background agent sessions.

Bare `claude agents` is an interactive, TTY-oriented view; the scripting
surface is `claude agents --json`, which "Print[s] active sessions as a JSON
array and exit[s] ... does not require a TTY". This module uses `--json` and
decodes that array, so it returns **active sessions** (not configured agents).
This is distinct from `ClaudeWrapper.Agents`, which reads and writes the
agent-definition files under `~/.claude` directly.
Each element is the CLI's raw session map (string keys).

## Usage

    config = ClaudeWrapper.Config.new()

    # Active background sessions (decoded JSON array)
    {:ok, sessions} = ClaudeWrapper.Commands.Agents.list(config)

    # Include completed sessions too
    {:ok, sessions} = ClaudeWrapper.Commands.Agents.list(config, all: true)

    # Raw --json output string
    {:ok, json} = ClaudeWrapper.Commands.Agents.execute(config)

# `session`

```elixir
@type session() :: map()
```

A background-agent session as reported by `claude agents --json` (raw, string-keyed).

# `execute`

```elixir
@spec execute(
  ClaudeWrapper.Config.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}
```

Run `claude agents --json` and return the raw output string.

# `list`

```elixir
@spec list(
  ClaudeWrapper.Config.t(),
  keyword()
) :: {:ok, [session()]} | {:error, term()}
```

Run `claude agents --json` and return the decoded array of active sessions.

## Options

  * `:all` - include completed sessions, not just active ones (`--all`)
  * `:setting_sources` - comma-separated setting sources to load
    (e.g. `"user,project"`)

---

*Consult [api-reference.md](api-reference.md) for complete listing*