docs(README): add newcomer orientation, ZSH plugin reference, and sync CLI docs#2862
Merged
tusharmath merged 4 commits intoantinomyhq:mainfrom Apr 7, 2026
Merged
Conversation
…c CLI docs
Adds onboarding context and documents the ZSH plugin system, which was not
covered in the README. Also updates the CLI reference to match the current
binary and clarifies a few configuration details.
What's added:
- "How Forge Works: Three Modes" section orienting newcomers to the three
distinct usage patterns: Interactive TUI, One-Shot CLI (-p), and ZSH Plugin.
Includes a note that `forge conversation resume <id>` opens the interactive
TUI (not a one-shot command), which is a common point of confusion.
- "ZSH Plugin: The `:` Prefix System" section with full coverage of agents
(forge/sage/muse, aliases :ask/:plan), prompt sending, file attachment via
@ + Tab, conversation management (:new, :conversation, :clone, :rename,
:retry, :copy, :dump, :compact), git integration (:commit, :commit-preview),
shell tools (:suggest, :edit), session-only vs persistent config options,
skills (built-in and custom), AGENTS.md, custom agents/commands, semantic
search/workspace, and a quick-reference table of all : commands.
- "Subcommands" section listing all forge subcommands by category.
What's updated:
- Command-Line Options table: reflects current flags (--conversation-id,
--agent, -C/--directory, --sandbox); removes flags not present in the
current CLI (-c, -w, -r).
- MCP section: replaces commands from an earlier version (add, add-json, get)
with the current subcommands (import, show, remove, reload); makes config
paths explicit (./.mcp.json for project-local, ~/forge/.mcp.json for global).
- ZSH plugin env var comment: corrected from # prefix to : prefix.
- Global config path: corrected from ~/.forge/.forge.toml to ~/forge/.forge.toml
(source: crates/forge_infra/src/env.rs line 27-29, h.join("forge")).
- Three minor grammar fixes (missing comma, pronoun clarity, sentence structure).
|
|
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
Collaborator
|
Many many thanks! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds onboarding context and documents the ZSH plugin system, which was not
covered in the README. Also updates the CLI reference to match the current
binary and clarifies a few configuration details.
What's added
distinct usage patterns: Interactive TUI, One-Shot CLI (
-p), and ZSH Plugin.Includes a note that
forge conversation resume <id>opens the interactiveTUI (not a one-shot command), which is a common point of confusion.
:Prefix System" section with full coverage of agents(forge/sage/muse, aliases
:ask/:plan), prompt sending, file attachment via@+ Tab, conversation management (:new,:conversation,:clone,:rename,:retry,:copy,:dump,:compact), git integration(
:commit,:commit-preview), shell tools (:suggest,:edit),session-only vs persistent config options, skills (built-in and custom),
AGENTS.md, custom agents/commands, semantic search/workspace, and aquick-reference table of all
:commands.forgesubcommands by category.What's updated
--conversation-id,--agent,-C/--directory,--sandbox); removes flags not present in thecurrent CLI (
-c,-w,-r).add,add-json,get) with the current subcommands (import,show,remove,reload);makes config paths explicit (
./.mcp.jsonfor project-local,~/forge/.mcp.jsonfor global).#prefix to:prefix.~/.forge/.forge.tomlto~/forge/.forge.toml(source:crates/forge_infra/src/env.rsline 27-29,h.join("forge")).