Skip to content

docs: refresh README positioning and getting started#168

Merged
edwin-zvs merged 10 commits into
mainfrom
readme-capabilities-getting-started
May 23, 2026
Merged

docs: refresh README positioning and getting started#168
edwin-zvs merged 10 commits into
mainfrom
readme-capabilities-getting-started

Conversation

@edwin-zvs

Copy link
Copy Markdown
Contributor

Summary

  • Reposition README around agentd as a terminal cockpit for a fleet of coding agents
  • Add benefit-oriented sections: Why agentd, what you can do with it, and core capabilities
  • Expand getting started into build, daemon, first sessions, TUI, and zarvis steps

Testing

  • cargo build --workspace
  • scripts/smoke.sh
  • git diff --check

No screenshot/video: documentation-only change.

Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated

@edwin-zvs edwin-zvs left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

first round of review

@edwin-zvs

Copy link
Copy Markdown
Contributor Author

Addressed review feedback in 74e5b85:

  • Removed the early status line and shortened the intro wording.
  • Updated harness list to mention Claude Code, Codex, Antigravity, Zarvis, and future harnesses.
  • Removed the separate "What you can do with it" section.
  • Removed the CLI-first getting-started flow; now it jumps from daemon startup to opening the TUI.
  • Replaced "Core capabilities" with a Documentation section.
  • Moved the deeper reference material into separate docs pages under docs/:
    • docs/architecture.md
    • docs/harnesses.md
    • docs/zarvis.md
    • docs/mcp.md
    • docs/configuration.md

Validation:

  • cargo build --workspace
  • scripts/smoke.sh (passed on rerun; first attempt hit the existing daemon socket startup race)
  • git diff --check

Comment thread README.md Outdated
Bare names auto-detect: `gpt-*` / `o[1-5]*` → OpenAI, `claude-*` →
Anthropic, anything else → Ollama. When in doubt, use the explicit
prefix.
## Smoke test

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove Smoke test section from README.md

Comment thread docs/harnesses.md Outdated
be loaded, or whose harness rejects the respawn are marked `Errored`
(transcript + scrollback remain readable).

Deferred to later milestones:

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove this section

Comment thread docs/harnesses.md Outdated
@@ -0,0 +1,146 @@
# Harnesses and session modes

## Milestone 1 scope

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's remove this section

Comment thread docs/mcp.md Outdated
@@ -0,0 +1,32 @@
# Agent-controlled agentd (MCP)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we name it 'Unified tool layer'? Also name it in this way from README

Comment thread docs/mcp.md Outdated
- Passes `--mcp-config <path>` to the child
- Sets `AGENTD_SESSION_ID=<session_id>` in the child's environment

The MCP server exposes a read + write tool surface that mirrors the IPC:

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

list of mcp server and tools organized in sections and table, rather than statements

Comment thread docs/zarvis.md Outdated
# zarvis built-in agent


`zarvis` is a self-contained headless agent that ships with agentd. It

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove ('headless'). Also mention "many PRs for agentd repository has been made from 'zarvis'"

@edwin-zvs edwin-zvs left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

left more comments

@edwin-zvs

Copy link
Copy Markdown
Contributor Author

Addressed the latest review feedback in b6438a7:

  • Removed the README Smoke test section.
  • Removed the Milestone 1 scope and deferred/later-milestones sections from docs/harnesses.md.
  • Renamed MCP docs to Unified tool layer and updated the README documentation link.
  • Reworked the unified tool layer page into tables for MCP injection, environment variables, fleet-control tools, and browser tools.
  • Updated Zarvis intro to remove "headless" and mention that many agentd PRs have been made from Zarvis sessions.

Validation:

  • cargo build --workspace
  • scripts/smoke.sh (passed on retry; first smoke attempt still hit the known daemon socket startup race)
  • git diff --check

@edwin-zvs

Copy link
Copy Markdown
Contributor Author

Added remote-control docs in 59d4f4b:

  • README now calls out as a benefit: browser-accessible web client, QR code, basic auth, and local modeline badge for attached remote clients.
  • now has a Remote control section covering , password override, stop, debug/local-only mode, , basic auth, and URL persistence across daemon restart when possible.

Validation: .

@edwin-zvs

Copy link
Copy Markdown
Contributor Author

Added remote-control docs in 59d4f4b:

  • README now calls out /remote-control as a benefit: browser-accessible web client, QR code, basic auth, and local modeline badge for attached remote clients.
  • docs/configuration.md now has a Remote control section covering /remote-control, password override, stop, debug/local-only mode, AGENTD_REMOTE_WS_PORT, basic auth, and URL persistence across daemon restart when possible.

Validation: git diff --check.

Comment thread README.md Outdated
output, spawn helpers, send input, inspect diffs, and drive Chrome.
- **Remote control when you step away** — `/remote-control` opens a
browser-accessible web client with a QR code, basic auth, and a local modeline
badge when remote clients are attached.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove 'basic auth, and a local ....'. Instead "Connect from your phone, no service signup, no setup required"

@edwin-zvs

Copy link
Copy Markdown
Contributor Author

Addressed the latest README wording comment in 9d TBD after push: the remote-control bullet now says it opens a browser-accessible client with a QR code and emphasizes connecting from your phone with no service signup or setup required.

Validation: git diff --check.

@edwin-zvs

Copy link
Copy Markdown
Contributor Author

Tuned the README tone in b985fec to hint at a more tactile, alive terminal experience without naming specific visual effects:

  • intro now frames agentd as “a terminal that feels alive under your hands”
  • Why section adds “fast to read, tactile to drive”
  • cockpit/native PTY copy now leans into terminal feel and preserving the real shape of tools
  • getting started ends with staying “in the flow”

Validation: git diff --check.

Comment thread README.md Outdated
# agentd

A terminal **agent fleet** — run and supervise multiple coding-agent sessions across heterogeneous harnesses (Claude Code, Codex, generic shell, ...) from one TUI.
**Command a fleet of coding agents without losing the thread.**

@edwin-zvs edwin-zvs May 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Command a feet of agents, designed for hackers"

Comment thread README.md Outdated
Launch, watch, steer, and compose multiple AI coding sessions in a workspace
that feels alive on the wire. Keep Claude Code, Codex, Antigravity, Zarvis, shell
tasks, and future harnesses moving together instead of juggling tabs, transcripts,
and background processes.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Create Codex, Claude Code, Antigravity, Zarvis sessions all in one place. Or let your agent coordinate them on terminal that is crafted hardcore hackers like you. Remote control from your phone when you're in motion.

Comment thread README.md Outdated

Status: **early — M2 (PTY mode) just landed. Wire protocols may still break.**
Create Codex, Claude Code, Antigravity, and Zarvis sessions all in one place. Or
let your agent coordinate them in a workspace crafted for hardcore hackers like

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in this particular case, let's use word 'terminal'.

"in a workspace crafted for" -> "in a terminal"

@edwin-zvs
edwin-zvs merged commit 57857c1 into main May 23, 2026
1 check passed
@edwin-zvs
edwin-zvs deleted the readme-capabilities-getting-started branch May 23, 2026 15:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant