Skip to main content
Glama
dwgx

SmartCLI

by dwgx
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

start

Spawn a program in a detached, persistent session and return its ID to control it across tool calls.

Instructions

Spawn a program in a new detached, persistent session and return its id.

The session survives across tool calls (a localhost-only daemon owns the live PtySession). cmd is the command line to spawn, e.g. "python3" or "lazygit". cwd and env configure only the controlled child process. Returns {"ok", "sid"} on success. Use the returned sid for every other tool.

Server-side limits (violations return an error): at most 8 concurrent sessions by default (tunable via SMARTCLI_MAX_SESSIONS); sid must be 1-64 chars matching [A-Za-z0-9][A-Za-z0-9_.-]*; env keys must be valid identifiers and may not start with SMARTCLI_TUI_; cwd must be an existing directory; terminal size is capped at 1000 cols x 500 rows (100000 cells). Note: env values pass through the process command line briefly (visible in ps) — avoid secrets.

detect_child_exit (default false) makes this session's waits END when the child dies instead of sitting out the remaining timeout: a program that crashes on your first input costs one poll cycle instead of the whole ceiling. Off is exactly the previous behaviour. On, every wait tool also reports exited (true only when the wait ended that way), and wait_ready reports reason: "EXITED" alongside the usual MARKER/STABLE/TIMEOUT.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cmdYes
cwdNo
envNo
sidNo
colsNo
rowsNo
detect_child_exitNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.4
    • addedInput schema / properties / detect_child_exit
      Added value: +{
+  "default": false,
+  "title": "Detect Child Exit",
+  "type": "boolean"
+}
  2. First observedv0.2.1

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) by disclosing the daemon-owned persistent session model, the 8-session concurrency cap, sid format constraints, env key restrictions, cwd existence requirement, terminal size ceiling, and the ps-visible secret leak risk. It also explains the detect_child_exit behavior change and its effect on wait/reporting semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then organized into constraints and the detect_child_exit note. The detect_child_exit paragraph is longer than strictly necessary, but each sentence adds operational value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotation coverage of the details, the description supplies the return shape ({ok, sid}), the persistence model, all constraint-based failure modes, and the wait-tool interactions. Nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the load: it documents cmd, cwd, env, sid (with format rules), and detect_child_exit. cols/rows are only implied via the terminal-size cap and are not given names or units, leaving a small gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Spawn a program in a new detached, persistent session') plus the return value ('return its id'), and the 'Use the returned sid for every other tool' line implies its role as the entry point of the sibling family. An agent can distinguish it from close/list_sessions/send_keys without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly indicates this is the first tool to call and that all other tools need the returned sid, and gives explicit guidance on when to enable detect_child_exit (programs that may crash on first input). It does not explicitly name an alternative tool or state when NOT to use it, so it falls short of the 5 bar.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools