From fa3c821a6b51d3d89183c1aae87f5b45febce685 Mon Sep 17 00:00:00 2001 From: factory-davidgu Date: Tue, 19 May 2026 06:39:15 -0700 Subject: [PATCH] docs(cli): comprehensive CLI documentation update - Add 12 missing slash commands to CLI reference table - Add missing CLI commands (search, computer, mcp, plugin, daemon) - Add 10 missing CLI flags including mission mode flags - Add 30+ keyboard shortcuts (image paste, Tab reasoning, @ autocomplete, history, readline) - Add Mermaid ASCII rendering documentation - Add 25+ missing settings across 7 categories including enterprise settings - Remove deprecated/non-functional settings (todoDisplayMode, specSaveEnabled, etc.) - Fix incorrect setting defaults, option values, and enterprise field names - Add missing droid exec flags with mission mode section - Replace stale readiness-report Coming Soon with /readiness-fix docs - Add mission configuration details (missionModelSettings, --mission, missionPolicy) - Expand power user guide from 4 to 14+ feature topics - Expand quickstart shortcuts and slash commands sections - Add feature capabilities overview to getting-started page - Add enterprise MCP policy, GenerateDroid, plugin CLI reference - Fix broken internal links and anchor IDs - Japanese translations for all changes across 8+ pages Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- docs/cli/configuration/custom-droids.mdx | 16 ++ docs/cli/configuration/mcp.mdx | 24 ++ docs/cli/configuration/plugins.mdx | 26 ++ docs/cli/configuration/settings.mdx | 95 +++++++ docs/cli/droid-exec/overview.mdx | 105 ++++++-- docs/cli/features/missions.mdx | 64 +++++ docs/cli/features/readiness-report.mdx | 44 +++- docs/cli/getting-started/overview.mdx | 10 + docs/cli/getting-started/quickstart.mdx | 32 ++- docs/cli/user-guides/become-a-power-user.mdx | 164 +++++++++++- docs/jp/cli/configuration/custom-droids.mdx | 16 ++ docs/jp/cli/configuration/mcp.mdx | 24 ++ docs/jp/cli/configuration/plugins.mdx | 26 ++ docs/jp/cli/configuration/settings.mdx | 95 +++++++ docs/jp/cli/droid-exec/overview.mdx | 105 ++++++-- docs/jp/cli/features/missions.mdx | 64 +++++ docs/jp/cli/features/readiness-report.mdx | 44 +++- docs/jp/cli/getting-started/overview.mdx | 10 + docs/jp/cli/getting-started/quickstart.mdx | 32 ++- .../cli/user-guides/become-a-power-user.mdx | 149 ++++++++++- docs/jp/reference/cli-reference.mdx | 233 ++++++++++++++---- docs/reference/cli-reference.mdx | 228 +++++++++++++---- 22 files changed, 1426 insertions(+), 180 deletions(-) diff --git a/docs/cli/configuration/custom-droids.mdx b/docs/cli/configuration/custom-droids.mdx index ea218af4..342b2574 100644 --- a/docs/cli/configuration/custom-droids.mdx +++ b/docs/cli/configuration/custom-droids.mdx @@ -45,6 +45,22 @@ Custom droids live as `.md` files under either your project's `.factory/droids/` Changes to droid files are picked up on the next menu open or Task tool invocation. +### AI-assisted droid generation + +Don't want to write the system prompt by hand? Droid ships with a built-in `GenerateDroid` tool that creates a complete custom droid configuration from a short description. Just describe what the droid should do — e.g. "review pull requests for security issues, focused on Node.js services" — and Droid will: + +- Suggest a normalized `name` +- Draft a focused system prompt +- Pick a sensible `tools` set and `model` +- Save the resulting `.md` file to your chosen project or personal location + +You can invoke it two ways: + +- From the **Create a new Droid** wizard in `/droids`, choose the AI-generated prompt option and provide a description. +- Ask the assistant directly: "Use `GenerateDroid` to create a droid that…" and pass `location: project` or `location: personal` to control where the file is saved. + +This is the fastest way to scaffold a new droid; you can always open the generated `.md` file and tweak the prompt, model, or tool list afterwards. + --- ## 4 · Configuration diff --git a/docs/cli/configuration/mcp.mdx b/docs/cli/configuration/mcp.mdx index 9f839cab..305e6ce6 100644 --- a/docs/cli/configuration/mcp.mdx +++ b/docs/cli/configuration/mcp.mdx @@ -298,3 +298,27 @@ For **http** servers: Droid automatically reloads when the configuration file changes, so servers are immediately available after adding them. +## Enterprise MCP policy + +Organizations can centrally control which MCP servers are allowed via the `mcpPolicy` setting in org-managed settings. This lets administrators restrict MCP access at the org level so users can only connect to vetted servers. + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `enabled` | `boolean` | Toggle MCP support on or off for the org. When `false`, all MCP servers are blocked. | +| `allowlist` | `string[]` | Optional list of server names users are permitted to enable. When set, any server not on the list is blocked. | + +**Example org-managed settings:** + +```json +{ + "mcpPolicy": { + "enabled": true, + "allowlist": ["linear", "sentry", "notion"] + } +} +``` + + + `mcpPolicy` is an enterprise/org-level setting and is enforced through managed settings — individual users cannot override it. Servers blocked by policy will not appear in the `/mcp` registry browser or load from `mcp.json`. + + diff --git a/docs/cli/configuration/plugins.mdx b/docs/cli/configuration/plugins.mdx index 6c384eab..7c352ab0 100644 --- a/docs/cli/configuration/plugins.mdx +++ b/docs/cli/configuration/plugins.mdx @@ -286,6 +286,32 @@ For organizations that need centralized control over approved plugins, see [Ente Droid is compatible with plugins built for Claude Code. If you find a Claude Code plugin you'd like to use, you can install it directly - the plugin format is interoperable. See the [Claude Code plugins documentation](https://code.claude.com/docs/en/plugins) for more details. +## CLI command reference + +Quick reference for the `droid plugin` subcommands. All commands accept `--scope user|project` (alias `-s`) to control where the plugin is installed; omit the flag to be prompted. + +| Command | Purpose | Example | +| :------ | :------ | :------ | +| `droid plugin install ` | Install a plugin from a registered marketplace. Alias: `droid plugin i`. | `droid plugin install droid-control@factory-plugins --scope project` | +| `droid plugin uninstall ` | Remove an installed plugin. Alias: `droid plugin remove`. | `droid plugin uninstall droid-control@factory-plugins` | +| `droid plugin update [plugin@marketplace]` | Update a specific plugin, or all plugins when called without an argument. | `droid plugin update droid-control@factory-plugins` | +| `droid plugin list` | List installed plugins, optionally scoped. | `droid plugin list --scope user` | +| `droid plugin marketplace` | Manage marketplaces (`add`, `remove`, `list`, `update`). | `droid plugin marketplace add https://github.com/Factory-AI/factory-plugins` | + +**Common workflows:** + +```bash +droid plugin marketplace add https://github.com/Factory-AI/factory-plugins +droid plugin install droid-control@factory-plugins +droid plugin list +droid plugin update +droid plugin uninstall droid-control@factory-plugins +``` + + + Prefer the interactive `/plugins` UI for browsing and one-off installs. Use the CLI when scripting onboarding, CI setup, or shared dotfiles. + + ## Next steps diff --git a/docs/cli/configuration/settings.mdx b/docs/cli/configuration/settings.mdx index b36d3449..184338a1 100644 --- a/docs/cli/configuration/settings.mdx +++ b/docs/cli/configuration/settings.mdx @@ -154,6 +154,101 @@ Commands that appear in both lists default to the denylist behavior. Any command Review and update these arrays periodically to match your workflow and security posture, especially when sharing configurations across teams. +## Session defaults + +Defaults applied when a new session starts. See also `sessionDefaultSettings.interactionMode` and `sessionDefaultSettings.autonomyLevel` in the table above. + +| Setting | Type | Options | Default | Description | +| ------------------------------------------------ | ------ | ---------------------------------------- | -------------- | ---------------------------------------------------------- | +| `sessionDefaultSettings.specModeModel` | string | Any [available model ID](/models) | Inherits model | Override the model used when sessions start in Spec Mode. | +| `sessionDefaultSettings.specModeReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort applied to the spec model. | + +## Display and UI + +Tune how droid renders content in the terminal. + +| Setting | Type | Options | Default | Description | +| -------------------------- | --------- | -------------------------------------- | ------------ | -------------------------------------------------------------------------------------------- | +| `toolResultDisplay` | string | `expanded`, `compact` | `expanded` | How tool results are rendered in the transcript. | +| `showTokenUsageIndicator` | boolean | `true`, `false` | `false` | Show the live token usage indicator at the bottom of the input. | +| `logoAnimation` | string | `once`, `always`, `off` | `once` | Animate the droid logo on startup. | +| `theme` | string | Theme ID (see `/themes`) | System theme | Color theme used by the TUI. | +| `overrideTerminalColors` | boolean | `true`, `false` | `false` | Force droid's theme to override the terminal's color scheme. | +| `nerdFont` | boolean | `true`, `false` | `false` | Enable Nerd Font glyphs in the UI (requires a Nerd Font in your terminal). | + +## Additional sound and notification settings + +Extends the [Sound notifications](#sound-notifications) section with toggles for the bell, per-event focus modes, and subagent activity. + +| Setting | Type | Options | Default | Description | +| -------------------------------- | ------- | -------------------------------------- | --------- | -------------------------------------------------------------------- | +| `subagentSounds` | string | `on`, `off` | `off` | Play sounds for subagent lifecycle events (start, complete, error). | + +## Mission settings + +Configure [Missions](/cli/features/missions) — multi-agent orchestration runs. + +| Setting | Type | Options | Default | Description | +| ---------------------------------------------------- | ------- | ---------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------- | +| `missionModelSettings.workerModel` | string | Any [available model ID](/models) | Inherits | Default model used by mission worker subagents. | +| `missionModelSettings.workerReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort for mission workers. | +| `missionModelSettings.validationWorkerModel` | string | Any [available model ID](/models) | Inherits | Model used by mission validators (scrutiny / user-testing workers). | +| `missionModelSettings.validationWorkerReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort for validation workers. | +| `missionModelSettings.skipScrutiny` | boolean | `true`, `false` | `false` | Skip scrutiny validation milestones during missions. | +| `missionModelSettings.skipUserTesting` | boolean | `true`, `false` | `false` | Skip user-testing validation milestones during missions. | +| `missionOrchestratorModel` | string | Any [available model ID](/models) | Inherits | Model used by the mission orchestrator. | +| `missionOrchestratorReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort for the mission orchestrator. | +| `keepSystemAwakeDuringMissions` | boolean | `true`, `false` | `true` | Prevent the OS from sleeping while a mission is running. | + +## Context and compaction + +Controls when and how droid compacts the conversation to stay within the model's context window. + +| Setting | Type | Options | Default | Description | +| -------------------------------- | ------- | ---------------------------------------- | --------------- | ------------------------------------------------------------------------------------------ | +| `compactionTokenLimit` | number | Token count | Model-dependent | Token threshold that triggers automatic compaction of the current session. | +| `compactionTokenLimitPerModel` | object | `{ "": number }` map | `{}` | Per-model overrides for `compactionTokenLimit`. | +| `compactionModelMode` | string | `same`, `` | `same` | Which model performs compaction: `same` uses the current session model, or specify a model ID. | + +## Spec mode settings + +Controls the persistent spec store created by Spec Mode. + +| Setting | Type | Options | Default | Description | +| ----------------- | ------- | ------------------------ | ----------------------------- | -------------------------------------------------------------------------- | +| `specSaveDir` | string | Directory path | `~/.factory/specs` | Directory where saved specs are written. Supports `~` expansion. | + +## Infrastructure + +System-level settings for status line, worktrees, and request timeouts. + +| Setting | Type | Options | Default | Description | +| ---------------------- | ------- | ------------------------------------------------------------------------------------------------ | --------------------- | ---------------------------------------------------------------------------------------------------- | +| `statusLine` | object | `{ "command": string, "padding"?: number, "maxRows"?: number }` | unset | Custom status line configuration. The `command` is executed and its stdout rendered above the input. Configure interactively with `/statusline`. | +| `worktreeDirectory` | string | Directory path | `~/.factory/worktrees` | Default parent directory for git worktrees created with `--worktree` / `-w`. | +| `llmRequestTimeout` | number | Milliseconds | Product default | Timeout for individual LLM requests before they are aborted. | + +## Enterprise and org-level settings + + +**Enterprise / Org-level.** The settings below are typically managed by an organization administrator and pushed to members through the Factory web app or a managed `settings.json`. Individual users generally do not set these directly. + + +| Setting | Type | Options | Default | Description | +| ------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | +| `maxAutonomyLevel` | string | `off`, `low`, `medium`, `high` | `high` | **Enterprise.** Maximum [Autonomy Level](/cli/user-guides/auto-run) any session may use. Higher levels selected by users are clamped. | +| `modelPolicy` | object | `{ "allowedModelIds"?: string[], "blockedModelIds"?: string[], "allowCustomModels"?: boolean, "allowedBaseUrls"?: string[] }` | unset | **Enterprise.** Restrict which models members can select, control whether custom models are permitted, and allowlist base URLs for custom model providers. | +| `mcpPolicy` | object | `{ "enabled"?: boolean, "allowlist"?: string[] }` | unset | **Enterprise.** Control whether MCP servers can run and which servers are permitted. See [MCP](/cli/configuration/mcp). | +| `missionPolicy` | object | `{ "restrictedAccess"?: boolean, "allowedUserIds"?: string[] }` | unset | **Enterprise.** Restrict who can launch [Missions](/cli/features/missions). | +| `networkPolicy` | object | `{ "allowedIps": string[] }` | unset | **Enterprise.** Restrict outbound network access from droid sessions to the specified IPs or CIDR ranges in `allowedIps`. | +| `sandbox` | object | `{ "enabled"?: boolean, "mode"?: string, "filesystem"?: object, "network"?: object }` | unset | **Enterprise.** Sandbox configuration controlling filesystem and network isolation for tool execution. | +| `restrictMemberVisibility` | boolean | `true`, `false` | `false` | **Org-level.** Hide other org members from non-admin users. | +| `restrictApiKeyCreationToManagers` | boolean | `true`, `false` | `false` | **Org-level.** Only org managers may create API keys. | +| `sessionRetentionDays` | number | `14`–`365` | Org default | **Org-level.** How long synced session history is retained before deletion. | +| `wikiCloudSync` | boolean | `true`, `false` | `true` | **Org-level.** Sync generated [Wiki](/cli/features/wiki/overview) content to Factory cloud. | +| `managedComputersEnabled` | boolean | `true`, `false` | `false` | **Enterprise.** Enable Factory-managed remote computers for the org. | +| `byomComputersEnabled` | boolean | `true`, `false` | `false` | **Enterprise.** Allow members to register their own machines via `droid computer register` (BYOM). | + ## Example configuration ```json diff --git a/docs/cli/droid-exec/overview.mdx b/docs/cli/droid-exec/overview.mdx index ab84688b..691dcd92 100644 --- a/docs/cli/droid-exec/overview.mdx +++ b/docs/cli/droid-exec/overview.mdx @@ -51,21 +51,34 @@ Arguments: prompt The prompt to execute Options: - -o, --output-format Output format (default: "text") - --input-format Input format: stream-jsonrpc for multi-turn sessions - -f, --file Read prompt from file - --auto Autonomy level: low|medium|high - --skip-permissions-unsafe Skip ALL permission checks - allows all permissions (unsafe) - -s, --session-id Existing session to continue (requires a prompt) - -m, --model Model ID to use - -r, --reasoning-effort Reasoning effort (defaults per model) - --spec-model Model ID to use for spec mode - --use-spec Start in spec mode - --enabled-tools Enable specific tools (comma or space separated list) - --disabled-tools Disable specific tools (comma or space separated list) - --list-tools List available tools for the selected model and exit - --cwd Working directory path - -h, --help display help for command + -o, --output-format Output format (default: "text") + --input-format Input format: stream-jsonrpc for multi-turn sessions + -f, --file Read prompt from file + --auto Autonomy level: low|medium|high + --skip-permissions-unsafe Skip ALL permission checks - allows all permissions (unsafe) + -s, --session-id Existing session to continue (requires a prompt) + --fork Fork an existing session and continue from it + -m, --model Model ID to use + -r, --reasoning-effort Reasoning effort (defaults per model) + --spec-model Model ID to use for spec mode + --spec-reasoning-effort Reasoning effort for spec mode + --use-spec Start in spec mode + --enabled-tools Enable specific tools (comma or space separated list) + --disabled-tools Disable specific tools (comma or space separated list) + --list-tools List available tools for the selected model and exit + --cwd Working directory path + -w, --worktree [name] Run in a git worktree + --worktree-dir Directory for worktree creation + --tag Session tag (name or JSON, repeatable) + --log-group-id Log group ID for filtering logs + --append-system-prompt Append custom text to end of system prompt + --append-system-prompt-file Append file contents to end of system prompt + --mission Run in mission mode (multi-agent orchestration) + --worker-model Model for mission workers + --worker-reasoning-effort Reasoning effort for mission workers + --validator-model Model for mission validators + --validator-reasoning-effort Reasoning effort for mission validators + -h, --help display help for command ``` Use any [available model ID](/models) with `--model` or `--spec-model`. For custom models, see [Bring Your Own Key (BYOK)](/cli/byok/overview). @@ -408,6 +421,68 @@ The index corresponds to the position in the `customModels` array (0-based). Reasoning effort (`-r` / `--reasoning-effort`) is not yet supported for custom models, but coming soon. +## Sessions, tagging, and logs + +Forking lets you branch off an existing session without disturbing the original; the new run starts from the forked session's history and is assigned a fresh session ID. + +```bash +# Continue a session in-place +droid exec --session-id "next steps" + +# Branch off a session into a new run +droid exec --fork --auto low "try an alternative refactor" +``` + +Use `--tag` to attach searchable labels to a run. The flag is repeatable and accepts either a plain name or a JSON object for structured metadata. Pair it with `--log-group-id` to bucket logs from related runs together for easier filtering and aggregation downstream. + +```bash +droid exec \ + --tag release-v2 \ + --tag '{"name":"team","value":"platform"}' \ + --log-group-id ci-nightly \ + --auto low "run nightly checks and write report.md" +``` + +## Customizing the system prompt + +Use `--append-system-prompt` to append additional text to the end of the system prompt for a single run, or `--append-system-prompt-file` to append the contents of a file. Both flags can be combined and are useful for injecting project-specific guidance, style guides, or invariants without modifying global settings. + +```bash +droid exec \ + --append-system-prompt "Always prefer functional React components." \ + --auto low "review src/components for class-based components" + +droid exec \ + --append-system-prompt-file ./docs/style-guide.md \ + --auto low "lint prose in README.md against the style guide" +``` + +## Mission mode + +Mission mode runs `droid exec` as a multi-agent orchestrator that plans work, delegates to worker agents, and validates results. Enable it with `--mission` and optionally select dedicated models and reasoning effort levels for the worker and validator roles. + +```bash +droid exec --mission \ + --worker-model claude-sonnet-4-5-20250929 \ + --worker-reasoning-effort medium \ + --validator-model claude-sonnet-4-5-20250929 \ + --validator-reasoning-effort high \ + --auto medium \ + "ship the new billing webhook end-to-end" +``` + +### Mission mode flags + +| Flag | Description | +|------|-------------| +| `--mission` | Run in mission mode (multi-agent orchestration). | +| `--worker-model ` | Model ID used by mission worker agents. | +| `--worker-reasoning-effort ` | Reasoning effort for mission workers. | +| `--validator-model ` | Model ID used by mission validator agents. | +| `--validator-reasoning-effort ` | Reasoning effort for mission validators. | + +The top-level `-m, --model` and `-r, --reasoning-effort` flags still apply to the orchestrator itself; the worker and validator overrides only affect the agents the orchestrator spawns. + ## Batch and parallel patterns Shell loops (bounded concurrency): diff --git a/docs/cli/features/missions.mdx b/docs/cli/features/missions.mdx index a199b1eb..34305be7 100644 --- a/docs/cli/features/missions.mdx +++ b/docs/cli/features/missions.mdx @@ -135,6 +135,70 @@ Missions inherit your existing Droid configuration: - **Custom droids** -- Subagents configured in your project are available to workers. - **AGENTS.md** -- Workers follow your project conventions and coding standards. +## Headless mission execution + +Missions can also run non-interactively via `droid exec --mission`. This is useful for CI, scheduled jobs, and any environment where you want the orchestrator to plan and execute without a live TUI. + +```bash +droid exec --mission -f mission.md +``` + +You can override the models and reasoning effort used by the orchestrator's worker and validator agents: + +```bash +droid exec --mission \ + --worker-model claude-sonnet-4-6 \ + --worker-reasoning-effort medium \ + --validator-model claude-opus-4-7 \ + --validator-reasoning-effort high \ + -f mission.md +``` + +| Flag | Description | +| ----------------------------------- | ------------------------------------------------------------ | +| `--mission` | Run `droid exec` in mission mode (multi-agent orchestration). | +| `--worker-model ` | Model used for mission worker agents. | +| `--worker-reasoning-effort ` | Reasoning effort for mission worker agents. | +| `--validator-model ` | Model used for mission validator agents. | +| `--validator-reasoning-effort ` | Reasoning effort for mission validator agents. | + +See [`droid exec`](/cli/droid-exec/overview) for the full headless reference. + +## Configuration + +Missions are tuned through the `missionModelSettings` object and a few top-level keys. Set these in your global or project [settings](/cli/configuration/settings) file. + +| Setting | Description | +| ------------------------------------------------------ | ---------------------------------------------------------------------------- | +| `missionModelSettings.workerModel` | Default model used by mission worker subagents. | +| `missionModelSettings.workerReasoningEffort` | Reasoning effort for mission workers (`off`, `none`, `low`, `medium`, `high`). | +| `missionModelSettings.validationWorkerModel` | Model used by validation workers (scrutiny and user-testing). | +| `missionModelSettings.validationWorkerReasoningEffort` | Reasoning effort for validation workers. | +| `missionModelSettings.skipScrutiny` | Skip scrutiny validation milestones during missions. | +| `missionModelSettings.skipUserTesting` | Skip user-testing validation milestones during missions. | +| `missionOrchestratorModel` | Model used by the mission orchestrator. | +| `missionOrchestratorReasoningEffort` | Reasoning effort for the mission orchestrator. | +| `keepSystemAwakeDuringMissions` | Prevent the OS from sleeping while a mission is running. Defaults to `true`. | + + + Pairing a strong orchestrator model with a faster worker model is a common cost-quality tradeoff: planning and validation benefit most from extra reasoning, while routine worker tasks can use a lighter model. + + +### Enterprise: restricting mission access + +Organizations can restrict who is allowed to launch missions through the `missionPolicy` org-level setting: + +```json +{ + "missionPolicy": { + "restrictedAccess": true, + "allowedUserIds": ["user_123", "user_456"] + } +} +``` + +When `restrictedAccess` is `true`, only members listed in `allowedUserIds` can start new missions. See the [settings reference](/cli/configuration/settings) for the full enterprise policy surface. + ## Open questions Missions are early. We are shipping this as a research preview because there are fundamental questions we are still working through: diff --git a/docs/cli/features/readiness-report.mdx b/docs/cli/features/readiness-report.mdx index 71016ac0..10106f2e 100644 --- a/docs/cli/features/readiness-report.mdx +++ b/docs/cli/features/readiness-report.mdx @@ -11,9 +11,7 @@ The `/readiness-report` slash command evaluates your current repository against ## Prerequisites -Before using this command: - -- Enable the feature in `/settings` → `Experimental` → `Readiness Report` +- Run the command from inside a git repository with an `origin` remote configured (the repository URL is used to associate the report with your project in the Factory App). --- @@ -39,7 +37,6 @@ When you run `/readiness-report`, the droid performs a comprehensive evaluation 3. **Criteria Evaluation** — Checks the criteria across all five maturity levels 4. **Report Storage** — Persists the evaluation results for visualization in the Factory App 5. **Summary Output** — Prints a human-readable report with results from the evaluation -6. **Remediation _(Coming soon)_** — Option to select and automatically fix failing criteria --- @@ -111,12 +108,39 @@ All readiness reports are automatically saved and can be viewed in the [web dash --- -## Remediation (Coming Soon) +## Remediation with `/readiness-fix` + +Once you've generated a readiness report, the `/readiness-fix` slash command lets the droid automatically remediate the failing signals from the latest report — turning the report from a diagnostic tool into an automated improvement workflow. + +### What it does + +`/readiness-fix` fetches the most recent stored readiness report for your repository and starts an agent session that works through the failing criteria, implementing fixes such as adding pre-commit hooks, creating an `AGENTS.md`, configuring CI checks, or improving documentation. + +### Usage -After running `/readiness-report`, you'll soon be able to automatically fix failing criteria directly from the CLI: +Navigate to the same repository you ran `/readiness-report` against and run: + +```bash +droid +> /readiness-fix +``` -1. Review the evaluation results -2. Select which failing criteria you'd like to remediate -3. The droid will implement the fixes (e.g., add pre-commit hooks, create AGENTS.md, configure branch protection) +You can also pass additional natural-language instructions to focus the run: -This turns the report from a diagnostic tool into an automated improvement workflow. +```bash +> /readiness-fix prioritize style & validation; do not touch CI configuration +``` + +### What to expect + +1. **Report lookup** — The command resolves your repository from `git remote get-url origin` and fetches the latest readiness report stored for that repo. +2. **Agent session** — The droid plans and applies changes to address failing criteria, one at a time, just like a normal coding session. You can review and approve changes as they happen. +3. **Verification** — After fixes are applied, run `/readiness-report` again to re-score the repository and confirm signals have moved. + + + `/readiness-fix` requires that a readiness report has already been generated for the repo. If no prior report is found, run `/readiness-report` first. + + + + Treat `/readiness-fix` like any other agent run: review the proposed changes, run your tests, and commit only what looks good for your codebase. + diff --git a/docs/cli/getting-started/overview.mdx b/docs/cli/getting-started/overview.mdx index c072bfe7..5271f619 100644 --- a/docs/cli/getting-started/overview.mdx +++ b/docs/cli/getting-started/overview.mdx @@ -41,6 +41,16 @@ You're now connected to Factory's development agent from your terminal. [Try the **Quick tip:** Press `!` to toggle bash mode and run shell commands directly without AI interpretation. Press `Esc` to return to normal mode. See the [CLI Reference](/reference/cli-reference#bash-mode) for details. +## Key capabilities + +- **Missions**: Launch multi-agent projects where an orchestrator coordinates specialized worker droids to plan, implement, and validate larger features. Start one with `/missions` or run headlessly with `droid exec --mission`. [Learn more →](/cli/features/missions) +- **MCP**: Connect droid to external tools and data sources through the Model Context Protocol. Add servers with `droid mcp add` or manage them via `/mcp`. [Learn more →](/cli/configuration/mcp) +- **Custom Droids**: Define specialized subagents with their own system prompts, tools, and models for delegated tasks. Manage them through `/droids`. [Learn more →](/cli/configuration/custom-droids) +- **Skills**: Package reusable procedures and domain knowledge that droid can invoke on demand. Browse and create skills with `/skills` or `/create-skill`. [Learn more →](/cli/configuration/skills) +- **Hooks**: Automate behavior around the agent lifecycle by running shell commands before or after specific tool events. Configure them with `/hooks`. [Learn more →](/cli/configuration/hooks-guide) +- **Plugins**: Extend droid with installable bundles of slash commands, droids, skills, and hooks distributed through marketplaces. Install with `droid plugin install` or manage via `/plugins`. [Learn more →](/cli/configuration/plugins) +- **Exec Mode**: Run droid headlessly for scripts, CI/CD pipelines, and automation. Use `droid exec` with structured input and output formats. [Learn more →](/cli/droid-exec/overview) + ## What `droid` brings to your workflow - **End-to-end feature development**: From planning to implementation to testing - droid handles the complete development lifecycle while keeping you in control through transparent review workflows. diff --git a/docs/cli/getting-started/quickstart.mdx b/docs/cli/getting-started/quickstart.mdx index bc7b233e..9615bf17 100644 --- a/docs/cli/getting-started/quickstart.mdx +++ b/docs/cli/getting-started/quickstart.mdx @@ -150,16 +150,20 @@ Droid makes Git operations conversational and intelligent: Here are the key interactions you'll use daily: -| Action | What it does | How to use | -| ---------------- | ------------------------------ | ------------------------------ | -| Send message | Submit a task or question | Type and press **Enter** | -| Multi-line input | Write longer prompts | **Shift\+Enter** for new lines | -| Approve changes | Accept proposed modifications | Accept change in the TUI | -| Reject changes | Decline proposed modifications | Reject change in the TUI | -| Switch modes | Toggle between modes | **Shift\+Tab** | -| Bash mode | Run shell commands directly without AI interpretation | Press `!` on an empty input; `Esc` to return | -| View shortcuts | See all available commands | Press **?** | -| Exit session | Leave droid | **Ctrl\+C** or type `exit` | +| Action | What it does | How to use | +| ----------------- | ----------------------------------------------------- | -------------------------------------------- | +| Send message | Submit a task or question | Type and press **Enter** | +| Multi-line input | Write longer prompts | **Shift\+Enter** for new lines | +| Approve changes | Accept proposed modifications | Accept change in the TUI | +| Reject changes | Decline proposed modifications | Reject change in the TUI | +| Switch modes | Toggle between modes | **Shift\+Tab** | +| Bash mode | Run shell commands directly without AI interpretation | Press `!` on an empty input; `Esc` to return | +| Transcript view | Toggle detailed transcript with full message details | **Ctrl+O** | +| Mission control | Toggle Mission Control overlay (orchestrator sessions)| **Ctrl+T** | +| Close overlay | Dismiss the active overlay or menu | **Escape** | +| Scroll transcript | Navigate through previous turns | **Alt+Up** / **Alt+Down** | +| View shortcuts | See all available commands | Press **?** | +| Exit session | Leave droid | **Ctrl\+C** or type `exit` | ### Useful slash commands @@ -168,6 +172,14 @@ Quick shortcuts to common actions: - `/review` - Start AI-powered code review workflow ([learn more](/cli/features/code-review)) - `/settings` - Configure droid behavior, models, and preferences - `/model` - Switch between AI models mid-session +- `/sessions` - List and resume previous sessions +- `/fork` - Fork the current session into a new branch +- `/compress` - Compress/compact the current session to free up context +- `/missions` - Open the Missions menu to launch multi-agent projects +- `/droids` - Manage custom Droids (specialized subagents) +- `/skills` - Manage prompt-based skills (reusable procedures) +- `/hooks` - Manage tool execution hooks for lifecycle automation +- `/plugins` - Manage plugins and marketplaces - `/mcp` - Manage Model Context Protocol servers - `/account` - Open your Factory account settings in browser - `/billing` - View and manage your billing settings diff --git a/docs/cli/user-guides/become-a-power-user.mdx b/docs/cli/user-guides/become-a-power-user.mdx index ca34aaf3..9a5329c2 100644 --- a/docs/cli/user-guides/become-a-power-user.mdx +++ b/docs/cli/user-guides/become-a-power-user.mdx @@ -4,7 +4,7 @@ description: Maximize Droid performance with IDE integration, smart planning, an keywords: ['power user', 'advanced', 'tips', 'optimization', 'performance', 'productivity', 'efficiency', 'best practices'] --- -Want Droid to work faster, smarter, and with fewer iterations? These four power features transform good results into exceptional ones. Each technique saves tokens, reduces tool calls, and ships better code. +Want Droid to work faster, smarter, and with fewer iterations? The techniques on this page transform good results into exceptional ones. Each one saves tokens, reduces tool calls, and ships better code — start with the four foundational features, then layer on the workflow boosters below. @@ -146,10 +146,166 @@ Make your project self-correcting. When Droid can run the same verification tool **Critical:** Keep verification fast. Slow tests will make the end-to-end work slower. -## Combining all four for maximum impact +## Keyboard shortcuts — Navigate the TUI like a pro -These features compound. IDE plugin provides context → Spec Mode uses that context for better planning → AGENTS.md ensures consistent implementation → Agent readiness catches issues immediately. +The TUI ships with shortcuts for nearly every common action. Learn a handful and you'll stop reaching for the mouse or scrolling endlessly. + +| Shortcut | Action | +| --- | --- | +| `Ctrl+O` | Toggle the detailed transcript view (full message details) | +| `Ctrl+T` | Toggle Mission Control overlay (orchestrator sessions) | +| `Ctrl+N` | Cycle through available models | +| `Ctrl+L` | Cycle autonomy level (low / medium / high) | +| `Ctrl+Y` | Toggle `/btw` side-question scroll view | +| `Ctrl+E` | Toggle approval details | +| `Tab` | Cycle reasoning effort (`low` → `medium` → `high` → `off`) | +| `Shift+Tab` | Cycle interaction modes (Auto → Spec → Mission) | +| `@` | File path autocomplete — typing `@` triggers fuzzy file search | +| `Up` / `Down` | Navigate input history — cycle through previously submitted messages | +| `Double Escape` | Second press clears the input draft; a third Escape opens the rewind menu | +| `Ctrl+V` | Paste an image from the clipboard as an attachment | +| `?` | Toggle the help popup (when the input is empty) | +| `Ctrl+/` | Toggle the help popup (works even with content in the input) | +| `Ctrl+A` | Move the cursor to the start of the line | +| `Ctrl+W` | Delete the word before the cursor | +| `Ctrl+K` | Delete from the cursor to the end of the line | +| `Ctrl+U` | Delete from the cursor to the start of the line | +| `Ctrl+D` | Clear attached images, or forward-delete a character if none are attached | +| `Ctrl+R` | Rename the highlighted session (in the `/sessions` list view) | +| `Ctrl+X` | Archive the highlighted session (in the `/sessions` list view) | +| `Alt+Up` / `Alt+Down` | Scroll the transcript turn-by-turn | +| `Alt+PageUp` / `Alt+PageDown` | Jump between user turns only | +| `Shift+Enter` | Insert a newline in the prompt input | +| `Escape` | Close any active overlay or menu | +| `!` | Toggle bash mode when the input is empty | + + + See the full list in the [CLI reference](/reference/cli-reference#keyboard-shortcuts). + + +## Bash mode — Quick shell access without leaving the TUI + +Press `!` on an empty input to drop into bash mode. Anything you type runs in your shell, and the output stays in the transcript so Droid can see it on the next turn — no copy/paste required. + +``` +! git status +! npm test -- --watch=false +``` + +Use it to check state, run a quick build, or capture output you want Droid to react to. Press `Escape` or send an empty input to exit bash mode. + +## Worktrees — Run parallel sessions on the same repo + +The `--worktree` flag launches Droid inside a fresh git worktree so multiple sessions can edit the same repository without stepping on each other. Combine it with `--worktree-dir` (or the `worktreeDirectory` setting) to keep all worktrees in one place. + +```bash +droid --worktree feature-auth +droid --worktree feature-billing +``` + +Each session lives on its own branch, so you can run experiments in parallel and merge whichever results win. + +## Session management — `/sessions`, `/fork`, `/compress` + +Long-running work doesn't have to live in a single session. Use these commands to navigate, branch, and trim conversations as you go: + +- `/sessions` — list and resume any previous session +- `/fork` — branch the current session so you can explore an alternative without losing your place +- `/compress` — compact the transcript when you start hitting context limits (also available as `/compact` or `/handoff`) + +``` +/fork +/compress focus on the failing migration +``` + +Forking is especially powerful for "what if" experiments — branch, try the risky refactor, and come back to the original session if it doesn't pan out. + +## Speed and iteration — `/fast` + +`/fast` flips the current model into its fast variant for snappier turns when you're iterating on small edits or exploration. Toggle it back with `/fast off`. + +``` +/fast +``` + +## Context management — `/context` and `/btw` + +`/context` shows a live breakdown of your context window: how many tokens are spent on system prompts, files, tool results, and conversation. Use it to spot bloat before compaction kicks in. + +`/btw` lets you ask a side question — Droid answers in a separate scroll buffer (`Ctrl+Y` to view) without polluting the main transcript or shifting focus from the task. + +``` +/context +/btw what does the @decorator pattern in src/auth.ts do? +``` + +Together they keep the main session focused while still letting you research on the side. + +## Custom slash commands — `/commands` + +Save your most-used prompts as reusable shortcuts. `/commands` opens the manager where you can create, edit, and scope custom slash commands at the project or user level. + +``` +/commands +``` + +Define a `/ship` command that runs your release checklist, a `/triage` command that scans new bugs, or anything else you find yourself typing repeatedly. Custom commands accept arguments, so they compose well with the rest of your workflow. + +## Hooks — Automate around tool calls + +`/hooks` lets you register lifecycle scripts that fire before or after Droid runs tools — think pre-commit checks, audit logging, automatic formatters, or guardrails that reject risky shell commands. + +``` +/hooks +``` + +Hooks live in your settings and apply to every session, so they're an excellent way to enforce team conventions without repeating yourself in every prompt. + +## MCP integrations — `/mcp` + +The Model Context Protocol lets Droid talk to external tools — databases, issue trackers, design tools, internal services — through a standard interface. Manage servers with `/mcp` in the TUI or `droid mcp add/remove` from the command line. + +```bash +droid mcp add linear https://mcp.linear.app/sse --type http +``` + +Once connected, Droid can read tickets, query databases, or invoke any other capability the server exposes — all without bespoke integrations. + +## Missions — Coordinate large multi-agent projects + +For work that spans many features or files, switch to Missions with `/missions`. Droid plans the work, spawns specialist worker agents, and validates each milestone — closing the gap between "agent in a chat" and "team of agents executing a plan." + +``` +/missions +``` + +Configure worker and validator models via `missionModelSettings` and run them headlessly with `droid exec --mission`. See [Missions](/cli/features/missions) for the full guide. + +## Custom droids — Specialized agents on demand + +`/droids` manages your library of custom droids: subagents with their own system prompts, tool sets, and models. Use them to encapsulate expertise — a "frontend reviewer" droid, a "SQL migration writer" droid, a "release notes" droid — and invoke them from any session. + +``` +/droids +``` + +You can also generate a new droid from a natural-language description, then iterate on it like any other config. See [Custom droids](/cli/configuration/custom-droids) for details. + +## Customization — Sounds, themes, and statusline + +Make the TUI feel like home. `/themes` switches color schemes, `/statusline` configures a custom status bar, and the `completionSound`, `soundFocusMode`, and `subagentSounds` settings let you wire audio cues to important events (completion, awaiting input, subagent activity). + +``` +/themes +/statusline +``` + +Combine sound notifications with long-running missions to step away from the terminal without losing situational awareness. + +## Putting it all together + +These features compound. The IDE plugin and AGENTS.md feed Droid the context and conventions it needs; Spec Mode and Agent Readiness keep its first attempts on target; keyboard shortcuts, bash mode, and `/btw` keep your hands on the keyboard; `/fast`, worktrees, missions, and custom droids scale the work itself. - **Getting started?** Install the IDE plugin first—it's the fastest path to better results. Then add AGENTS.md with just your test commands. Build from there. + **Getting started?** Install the IDE plugin first—it's the fastest path to better results. Add AGENTS.md with your test commands, learn three or four shortcuts, and grow from there. diff --git a/docs/jp/cli/configuration/custom-droids.mdx b/docs/jp/cli/configuration/custom-droids.mdx index 828b1528..d34049f1 100644 --- a/docs/jp/cli/configuration/custom-droids.mdx +++ b/docs/jp/cli/configuration/custom-droids.mdx @@ -45,6 +45,22 @@ keywords: ['custom droids', 'subagents', 'agents', 'specialized agents', 'delega droid ファイルの変更は、次回のメニューオープンまたはTask ツール呼び出し時に反映されます。 +### AI による droid 生成 + +システムプロンプトを手書きしたくありませんか？ Droid には、短い説明から完全なカスタム droid 設定を作成する `GenerateDroid` ツールが組み込まれています。droid に何をさせたいかを記述するだけで（例：「Node.js サービスに焦点を当てて、セキュリティ問題のために PR をレビューする」）、Droid は以下を行います： + +- 正規化された `name` を提案 +- 焦点を絞ったシステムプロンプトを起草 +- 適切な `tools` セットと `model` を選択 +- 結果の `.md` ファイルを選択したプロジェクトまたは個人の場所に保存 + +次の 2 つの方法で呼び出せます： + +- `/droids` の **Create a new Droid** ウィザードから、AI 生成プロンプトオプションを選び、説明を入力します。 +- アシスタントに直接依頼します：「`GenerateDroid` を使って…するdroid を作って」と伝え、`location: project` または `location: personal` を渡してファイルの保存先を制御します。 + +これは新しい droid を雛形作成する最速の方法です。生成された `.md` ファイルはいつでも開いて、プロンプト、モデル、ツールリストを後から調整できます。 + --- ## 4 · 設定 diff --git a/docs/jp/cli/configuration/mcp.mdx b/docs/jp/cli/configuration/mcp.mdx index 2197f6b0..33f19da4 100644 --- a/docs/jp/cli/configuration/mcp.mdx +++ b/docs/jp/cli/configuration/mcp.mdx @@ -297,3 +297,27 @@ OAuthトークンはシステムキーリング（またはフォールバック ``` Droidは設定ファイルの変更時に自動的にリロードされるため、サーバーを追加した後すぐに利用可能になります。 + +## Enterprise MCP ポリシー + +組織は、組織管理設定の `mcpPolicy` 設定を通じて、許可される MCP サーバーを集中的に制御できます。これにより、管理者は組織レベルで MCP アクセスを制限し、ユーザーが検証済みのサーバーにのみ接続できるようにします。 + +| フィールド | 型 | 説明 | +| :--------- | :- | :--- | +| `enabled` | `boolean` | 組織の MCP サポートを有効または無効にします。`false` の場合、すべての MCP サーバーがブロックされます。 | +| `allowlist` | `string[]` | ユーザーが有効化を許可されるサーバー名の任意のリスト。設定されている場合、リストにないサーバーはすべてブロックされます。 | + +**組織管理設定の例：** + +```json +{ + "mcpPolicy": { + "enabled": true, + "allowlist": ["linear", "sentry", "notion"] + } +} +``` + + + `mcpPolicy` はエンタープライズ／組織レベルの設定で、管理設定を通じて適用されます。個々のユーザーが上書きすることはできません。ポリシーによってブロックされたサーバーは、`/mcp` のレジストリブラウザに表示されず、`mcp.json` からも読み込まれません。 + diff --git a/docs/jp/cli/configuration/plugins.mdx b/docs/jp/cli/configuration/plugins.mdx index f5c8be4a..76ea95e8 100644 --- a/docs/jp/cli/configuration/plugins.mdx +++ b/docs/jp/cli/configuration/plugins.mdx @@ -264,6 +264,32 @@ droid plugin install security-engineer@factory-plugins DroidはClaude Code向けに構築されたプラグインと互換性があります。使用したいClaude Codeプラグインを見つけた場合、直接インストールできます - プラグイン形式は相互運用可能です。詳細については[Claude Codeプラグインドキュメント](https://code.claude.com/docs/en/plugins)を参照してください。 +## CLI コマンドリファレンス + +`droid plugin` サブコマンドのクイックリファレンスです。すべてのコマンドは `--scope user|project`（エイリアス `-s`）を受け付け、プラグインのインストール先を指定できます。フラグを省略するとプロンプトが表示されます。 + +| コマンド | 目的 | 例 | +| :------- | :--- | :- | +| `droid plugin install ` | 登録済みのマーケットプレイスからプラグインをインストール。エイリアス: `droid plugin i`。 | `droid plugin install droid-control@factory-plugins --scope project` | +| `droid plugin uninstall ` | インストール済みのプラグインを削除。エイリアス: `droid plugin remove`。 | `droid plugin uninstall droid-control@factory-plugins` | +| `droid plugin update [plugin@marketplace]` | 特定のプラグインを更新。引数なしで呼び出すとすべてのプラグインを更新。 | `droid plugin update droid-control@factory-plugins` | +| `droid plugin list` | インストール済みのプラグインを一覧表示。スコープの指定も可能。 | `droid plugin list --scope user` | +| `droid plugin marketplace` | マーケットプレイスを管理（`add`、`remove`、`list`、`update`）。 | `droid plugin marketplace add https://github.com/Factory-AI/factory-plugins` | + +**よくあるワークフロー：** + +```bash +droid plugin marketplace add https://github.com/Factory-AI/factory-plugins +droid plugin install droid-control@factory-plugins +droid plugin list +droid plugin update +droid plugin uninstall droid-control@factory-plugins +``` + + + 閲覧やワンオフのインストールにはインタラクティブな `/plugins` UI を推奨します。オンボーディングのスクリプト化、CI セットアップ、共有のドットファイルでは CLI を利用してください。 + + ## 次のステップ diff --git a/docs/jp/cli/configuration/settings.mdx b/docs/jp/cli/configuration/settings.mdx index 844372e7..ea38a296 100644 --- a/docs/jp/cli/configuration/settings.mdx +++ b/docs/jp/cli/configuration/settings.mdx @@ -159,6 +159,101 @@ droidイベントの音声フィードバックを設定します： ``` これらの配列を定期的に見直し更新して、ワークフローとセキュリティ体制に合わせてください。特にチーム間で設定を共有する場合は重要です。 +## セッションデフォルト + +新しいセッションが開始されるときに適用されるデフォルト値です。上記の表にある`sessionDefaultSettings.interactionMode`と`sessionDefaultSettings.autonomyLevel`もあわせて参照してください。 + +| 設定 | 型 | オプション | デフォルト | 説明 | +| ------- | ------ | ------- | ------- | ----------- | +| `sessionDefaultSettings.specModeModel` | string | 任意の[利用可能なモデルID](/jp/models) | `model`を継承 | セッションがSpec Modeで開始されたときに使用するモデルを上書きします。 | +| `sessionDefaultSettings.specModeReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | モデルのデフォルト | Specモデルに適用される推論努力。 | + +## 表示とUI + +droidがターミナルでコンテンツをどのように描画するかを調整します。 + +| 設定 | 型 | オプション | デフォルト | 説明 | +| ------- | ------ | ------- | ------- | ----------- | +| `toolResultDisplay` | string | `expanded`, `compact` | `expanded` | ツール結果をトランスクリプトでどのように表示するか。 | +| `showTokenUsageIndicator` | boolean | `true`, `false` | `false` | 入力欄の下部にライブのトークン使用量インジケーターを表示します。 | +| `logoAnimation` | string | `once`, `always`, `off` | `once` | 起動時にdroidロゴをアニメーションさせます。 | +| `theme` | string | テーマID（`/themes`を参照） | システムテーマ | TUIで使用するカラーテーマ。 | +| `overrideTerminalColors` | boolean | `true`, `false` | `false` | droidのテーマでターミナルのカラースキームを強制的に上書きします。 | +| `nerdFont` | boolean | `true`, `false` | `false` | UIでNerd Fontのグリフを有効にします（ターミナルにNerd Fontが必要です）。 | + +## 追加の音声・通知設定 + +[音声通知](#音声通知)セクションを拡張し、ベル、イベントごとのフォーカスモード、サブエージェントのアクティビティに対するトグルを追加します。 + +| 設定 | 型 | オプション | デフォルト | 説明 | +| ------- | ------ | ------- | ------- | ----------- | +| `subagentSounds` | string | `on`, `off` | `off` | サブエージェントのライフサイクルイベント（開始、完了、エラー）の音声を再生します。 | + +## ミッション設定 + +[ミッション](/jp/cli/features/missions) — マルチエージェントオーケストレーションの実行を設定します。 + +| 設定 | 型 | オプション | デフォルト | 説明 | +| ------- | ------ | ------- | ------- | ----------- | +| `missionModelSettings.workerModel` | string | 任意の[利用可能なモデルID](/jp/models) | 継承 | ミッションのワーカーサブエージェントが使用するデフォルトモデル。 | +| `missionModelSettings.workerReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | モデルのデフォルト | ミッションワーカーの推論努力。 | +| `missionModelSettings.validationWorkerModel` | string | 任意の[利用可能なモデルID](/jp/models) | 継承 | ミッションのバリデーター（scrutiny / user-testingワーカー）が使用するモデル。 | +| `missionModelSettings.validationWorkerReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | モデルのデフォルト | バリデーションワーカーの推論努力。 | +| `missionModelSettings.skipScrutiny` | boolean | `true`, `false` | `false` | ミッション中のscrutiny検証マイルストーンをスキップします。 | +| `missionModelSettings.skipUserTesting` | boolean | `true`, `false` | `false` | ミッション中のuser-testing検証マイルストーンをスキップします。 | +| `missionOrchestratorModel` | string | 任意の[利用可能なモデルID](/jp/models) | 継承 | ミッションオーケストレーターが使用するモデル。 | +| `missionOrchestratorReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | モデルのデフォルト | ミッションオーケストレーターの推論努力。 | +| `keepSystemAwakeDuringMissions` | boolean | `true`, `false` | `true` | ミッション実行中にOSがスリープしないようにします。 | + +## コンテキストとコンパクション + +モデルのコンテキストウィンドウ内に収めるために、droidが会話をいつ・どのようにコンパクションするかを制御します。 + +| 設定 | 型 | オプション | デフォルト | 説明 | +| ------- | ------ | ------- | ------- | ----------- | +| `compactionTokenLimit` | number | トークン数 | モデル依存 | 現在のセッションの自動コンパクションをトリガーするトークンしきい値。 | +| `compactionTokenLimitPerModel` | object | `{ "": number }`マップ | `{}` | `compactionTokenLimit`のモデルごとの上書き。 | +| `compactionModelMode` | string | `same`, `` | `same` | コンパクションを実行するモデル：`same`は現在のセッションモデルを使用し、特定のモデルIDを指定することもできます。 | + +## Spec Mode設定 + +Spec Modeによって作成される永続的なspecストアを制御します。 + +| 設定 | 型 | オプション | デフォルト | 説明 | +| ------- | ------ | ------- | ------- | ----------- | +| `specSaveDir` | string | ディレクトリパス | `~/.factory/specs` | 保存されたspecを書き込むディレクトリ。`~`の展開をサポートします。 | + +## インフラストラクチャ + +ステータスライン、worktree、リクエストタイムアウトに関するシステムレベルの設定。 + +| 設定 | 型 | オプション | デフォルト | 説明 | +| ------- | ------ | ------- | ------- | ----------- | +| `statusLine` | object | `{ "command": string, "padding"?: number, "maxRows"?: number }` | 未設定 | カスタムステータスライン設定。`command`が実行され、その標準出力が入力欄の上に表示されます。`/statusline`で対話的に設定できます。 | +| `worktreeDirectory` | string | ディレクトリパス | `~/.factory/worktrees` | `--worktree` / `-w`で作成されるgit worktreeのデフォルト親ディレクトリ。 | +| `llmRequestTimeout` | number | ミリ秒 | 製品のデフォルト | 個々のLLMリクエストが中断されるまでのタイムアウト。 | + +## エンタープライズおよび組織レベルの設定 + + + **エンタープライズ / 組織レベル。** 以下の設定は通常、組織管理者によって管理され、Factory webアプリまたは管理された`settings.json`を通じてメンバーに配布されます。個々のユーザーが直接設定することは通常ありません。 + + +| 設定 | 型 | オプション | デフォルト | 説明 | +| ------- | ------ | ------- | ------- | ----------- | +| `maxAutonomyLevel` | string | `off`, `low`, `medium`, `high` | `high` | **エンタープライズ。** 任意のセッションで使用できる最大[自律レベル](/jp/cli/user-guides/auto-run)。ユーザーが選択したより高いレベルはこの値に制限されます。 | +| `modelPolicy` | object | `{ "allowedModelIds"?: string[], "blockedModelIds"?: string[], "allowCustomModels"?: boolean, "allowedBaseUrls"?: string[] }` | 未設定 | **エンタープライズ。** メンバーが選択できるモデルを制限し、カスタムモデルの許可可否を制御し、カスタムモデルプロバイダーのベースURLを許可リスト化します。 | +| `mcpPolicy` | object | `{ "enabled"?: boolean, "allowlist"?: string[] }` | 未設定 | **エンタープライズ。** MCPサーバーの実行可否と許可されるサーバーを制御します。[MCP](/jp/cli/configuration/mcp)を参照してください。 | +| `missionPolicy` | object | `{ "restrictedAccess"?: boolean, "allowedUserIds"?: string[] }` | 未設定 | **エンタープライズ。** [ミッション](/jp/cli/features/missions)を起動できるユーザーを制限します。 | +| `networkPolicy` | object | `{ "allowedIps": string[] }` | 未設定 | **エンタープライズ。** droidセッションからのアウトバウンドネットワークアクセスを `allowedIps` に指定したIPまたはCIDRレンジに制限します。 | +| `sandbox` | object | `{ "enabled"?: boolean, "mode"?: string, "filesystem"?: object, "network"?: object }` | 未設定 | **エンタープライズ。** ツール実行のファイルシステムとネットワーク隔離を制御するサンドボックス設定。 | +| `restrictMemberVisibility` | boolean | `true`, `false` | `false` | **組織レベル。** 管理者以外のユーザーから他の組織メンバーを非表示にします。 | +| `restrictApiKeyCreationToManagers` | boolean | `true`, `false` | `false` | **組織レベル。** 組織のマネージャーのみがAPIキーを作成できます。 | +| `sessionRetentionDays` | number | `14`–`365` | 組織のデフォルト | **組織レベル。** 同期されたセッション履歴が削除されるまで保持される日数。 | +| `wikiCloudSync` | boolean | `true`, `false` | `true` | **組織レベル。** 生成された[Wiki](/jp/cli/features/wiki/overview)コンテンツをFactoryクラウドに同期します。 | +| `managedComputersEnabled` | boolean | `true`, `false` | `false` | **エンタープライズ。** 組織でFactoryマネージドのリモートコンピューターを有効にします。 | +| `byomComputersEnabled` | boolean | `true`, `false` | `false` | **エンタープライズ。** メンバーが`droid computer register`で自分のマシンを登録できるようにします（BYOM）。 | + ## 設定例 ```json { diff --git a/docs/jp/cli/droid-exec/overview.mdx b/docs/jp/cli/droid-exec/overview.mdx index 3fe1a732..fbe989c2 100644 --- a/docs/jp/cli/droid-exec/overview.mdx +++ b/docs/jp/cli/droid-exec/overview.mdx @@ -50,21 +50,34 @@ Arguments: prompt The prompt to execute Options: - -o, --output-format Output format (default: "text") - --input-format Input format: stream-jsonrpc for multi-turn sessions - -f, --file Read prompt from file - --auto Autonomy level: low|medium|high - --skip-permissions-unsafe Skip ALL permission checks - allows all permissions (unsafe) - -s, --session-id Existing session to continue (requires a prompt) - -m, --model Model ID to use - -r, --reasoning-effort Reasoning effort (defaults per model) - --spec-model Model ID to use for spec mode - --use-spec Start in spec mode - --enabled-tools Enable specific tools (comma or space separated list) - --disabled-tools Disable specific tools (comma or space separated list) - --list-tools List available tools for the selected model and exit - --cwd Working directory path - -h, --help display help for command + -o, --output-format Output format (default: "text") + --input-format Input format: stream-jsonrpc for multi-turn sessions + -f, --file Read prompt from file + --auto Autonomy level: low|medium|high + --skip-permissions-unsafe Skip ALL permission checks - allows all permissions (unsafe) + -s, --session-id Existing session to continue (requires a prompt) + --fork Fork an existing session and continue from it + -m, --model Model ID to use + -r, --reasoning-effort Reasoning effort (defaults per model) + --spec-model Model ID to use for spec mode + --spec-reasoning-effort Reasoning effort for spec mode + --use-spec Start in spec mode + --enabled-tools Enable specific tools (comma or space separated list) + --disabled-tools Disable specific tools (comma or space separated list) + --list-tools List available tools for the selected model and exit + --cwd Working directory path + -w, --worktree [name] Run in a git worktree + --worktree-dir Directory for worktree creation + --tag Session tag (name or JSON, repeatable) + --log-group-id Log group ID for filtering logs + --append-system-prompt Append custom text to end of system prompt + --append-system-prompt-file Append file contents to end of system prompt + --mission Run in mission mode (multi-agent orchestration) + --worker-model Model for mission workers + --worker-reasoning-effort Reasoning effort for mission workers + --validator-model Model for mission validators + --validator-reasoning-effort Reasoning effort for mission validators + -h, --help display help for command ``` `--model`または`--spec-model`には、任意の[利用可能なモデルID](/jp/models)を使用できます。カスタムモデルについては、[Bring Your Own Key (BYOK)](/jp/cli/byok/overview)を参照してください。 @@ -371,6 +384,68 @@ droid exec --model "custom:My-Custom-Model-0" "analyze this codebase" 推論努力（`-r` / `--reasoning-effort`）はカスタムモデルではまだサポートされていませんが、近日対応予定です。 +## セッション、タグ付け、ログ + +Forkを使うと、元のセッションを乱すことなく既存セッションから分岐できます。新しい実行は分岐元セッションの履歴から開始され、新しいセッションIDが割り当てられます。 + +```bash +# Continue a session in-place +droid exec --session-id "next steps" + +# Branch off a session into a new run +droid exec --fork --auto low "try an alternative refactor" +``` + +`--tag` を使うと、実行に検索可能なラベルを付与できます。このフラグは繰り返し指定でき、プレーンな名前または構造化メタデータ用のJSONオブジェクトを受け付けます。`--log-group-id` と組み合わせて関連する実行のログを同じグループにまとめると、後段のフィルタリングや集計が容易になります。 + +```bash +droid exec \ + --tag release-v2 \ + --tag '{"name":"team","value":"platform"}' \ + --log-group-id ci-nightly \ + --auto low "run nightly checks and write report.md" +``` + +## システムプロンプトのカスタマイズ + +`--append-system-prompt` を使うと、単一実行のシステムプロンプトの末尾に追加テキストを付加できます。`--append-system-prompt-file` はファイルの内容を末尾に追加します。両方のフラグは組み合わせて使用でき、グローバル設定を変更することなくプロジェクト固有のガイダンス、スタイルガイド、不変条件を注入するのに便利です。 + +```bash +droid exec \ + --append-system-prompt "Always prefer functional React components." \ + --auto low "review src/components for class-based components" + +droid exec \ + --append-system-prompt-file ./docs/style-guide.md \ + --auto low "lint prose in README.md against the style guide" +``` + +## ミッションモード + +ミッションモードは、`droid exec` を作業を計画し、ワーカーエージェントに委任し、結果を検証するマルチエージェントオーケストレーターとして実行します。`--mission` で有効化し、ワーカーおよびバリデーターロール用の専用モデルと推論努力レベルをオプションで選択できます。 + +```bash +droid exec --mission \ + --worker-model claude-sonnet-4-5-20250929 \ + --worker-reasoning-effort medium \ + --validator-model claude-sonnet-4-5-20250929 \ + --validator-reasoning-effort high \ + --auto medium \ + "ship the new billing webhook end-to-end" +``` + +### ミッションモードのフラグ + +| フラグ | 説明 | +|------|-------------| +| `--mission` | ミッションモード（マルチエージェントオーケストレーション）で実行します。 | +| `--worker-model ` | ミッションワーカーエージェントが使用するモデルID。 | +| `--worker-reasoning-effort ` | ミッションワーカーの推論努力。 | +| `--validator-model ` | ミッションバリデーターエージェントが使用するモデルID。 | +| `--validator-reasoning-effort ` | ミッションバリデーターの推論努力。 | + +最上位の `-m, --model` と `-r, --reasoning-effort` フラグは引き続きオーケストレーター自体に適用されます。ワーカーおよびバリデーターのオーバーライドは、オーケストレーターが生成するエージェントにのみ影響します。 + ## バッチと並列パターン シェルループ（制限された並行性）： diff --git a/docs/jp/cli/features/missions.mdx b/docs/jp/cli/features/missions.mdx index 0c2371a9..f10fa8bf 100644 --- a/docs/jp/cli/features/missions.mdx +++ b/docs/jp/cli/features/missions.mdx @@ -135,6 +135,70 @@ Factory Missions は既存の Droid 設定を継承します： - **カスタム droids** -- プロジェクトで設定されたサブエージェントがワーカーで利用できます - **AGENTS.md** -- ワーカーはプロジェクトの慣例とコーディング標準に従います +## ヘッドレスでのミッション実行 + +ミッションは `droid exec --mission` を使って非対話的に実行することもできます。これは CI、スケジュール実行、ライブ TUI なしでオーケストレーターに計画と実行を任せたい環境で便利です。 + +```bash +droid exec --mission -f mission.md +``` + +オーケストレーターのワーカーエージェントと検証エージェントが使用するモデルや推論努力を上書きできます： + +```bash +droid exec --mission \ + --worker-model claude-sonnet-4-6 \ + --worker-reasoning-effort medium \ + --validator-model claude-opus-4-7 \ + --validator-reasoning-effort high \ + -f mission.md +``` + +| フラグ | 説明 | +| --------------------------------------- | ------------------------------------------------------------ | +| `--mission` | `droid exec` をミッションモード（マルチエージェントオーケストレーション）で実行します。 | +| `--worker-model ` | ミッションワーカーエージェントが使用するモデル。 | +| `--worker-reasoning-effort ` | ミッションワーカーエージェントの推論努力。 | +| `--validator-model ` | ミッション検証エージェントが使用するモデル。 | +| `--validator-reasoning-effort ` | ミッション検証エージェントの推論努力。 | + +ヘッドレス実行の完全なリファレンスは [`droid exec`](/jp/cli/droid-exec/overview) を参照してください。 + +## 設定 + +ミッションは `missionModelSettings` オブジェクトといくつかのトップレベルキーで調整できます。これらはグローバルまたはプロジェクトの[設定](/jp/cli/configuration/settings)ファイルで指定します。 + +| 設定 | 説明 | +| ------------------------------------------------------- | --------------------------------------------------------------------------------- | +| `missionModelSettings.workerModel` | ミッションワーカーサブエージェントが使用するデフォルトのモデル。 | +| `missionModelSettings.workerReasoningEffort` | ミッションワーカーの推論努力（`off`、`none`、`low`、`medium`、`high`）。 | +| `missionModelSettings.validationWorkerModel` | 検証ワーカー（scrutiny と user-testing）が使用するモデル。 | +| `missionModelSettings.validationWorkerReasoningEffort` | 検証ワーカーの推論努力。 | +| `missionModelSettings.skipScrutiny` | ミッション中の scrutiny 検証マイルストーンをスキップします。 | +| `missionModelSettings.skipUserTesting` | ミッション中のユーザーテスト検証マイルストーンをスキップします。 | +| `missionOrchestratorModel` | ミッションオーケストレーターが使用するモデル。 | +| `missionOrchestratorReasoningEffort` | ミッションオーケストレーターの推論努力。 | +| `keepSystemAwakeDuringMissions` | ミッション実行中に OS がスリープしないようにします。デフォルトは `true`。 | + + + 強力なオーケストレーターモデルと高速なワーカーモデルを組み合わせるのは、コストと品質のトレードオフとしてよくある選択です。計画と検証は追加の推論で恩恵を受けやすく、定型的なワーカータスクは軽量なモデルで十分です。 + + +### Enterprise: ミッションへのアクセス制限 + +組織は `missionPolicy` の組織レベル設定により、ミッションを起動できるユーザーを制限できます： + +```json +{ + "missionPolicy": { + "restrictedAccess": true, + "allowedUserIds": ["user_123", "user_456"] + } +} +``` + +`restrictedAccess` が `true` の場合、`allowedUserIds` に列挙されたメンバーのみが新しいミッションを開始できます。組織向けポリシーの全容は[設定リファレンス](/jp/cli/configuration/settings)を参照してください。 + ## 未解決の問題 Factory Missions は初期段階です。まだ取り組んでいる根本的な問題があるため、これをリサーチプレビューとして提供しています： diff --git a/docs/jp/cli/features/readiness-report.mdx b/docs/jp/cli/features/readiness-report.mdx index 8b9a0912..27c8237d 100644 --- a/docs/jp/cli/features/readiness-report.mdx +++ b/docs/jp/cli/features/readiness-report.mdx @@ -17,9 +17,7 @@ keywords: ## 前提条件 -このコマンドを使用する前に： - -- `/settings` → `Experimental` → `Readiness Report` で機能を有効化してください +- `origin` リモートが設定されている git リポジトリ内からコマンドを実行してください（リポジトリのURLは Factory App でレポートをプロジェクトに紐づけるために使用されます）。 --- @@ -45,7 +43,6 @@ droid 3. **基準評価** — 5つすべての成熟度レベルにわたって基準をチェック 4. **レポート保存** — Factory Appでの視覚化のため評価結果を永続化 5. **サマリー出力** — 評価結果を含む人間が読みやすいレポートを出力 -6. **修復 _（近日公開）_** — 失敗した基準を選択して自動修正するオプション --- @@ -117,12 +114,39 @@ Action Items: --- -## 修復（近日公開） +## `/readiness-fix` による修復 + +readiness レポートを生成した後は、`/readiness-fix` スラッシュコマンドを使うことで、最新レポートで失敗したシグナルを droid が自動的に修復できます。これにより、レポートは診断ツールから自動化された改善ワークフローへと変わります。 + +### 何をするか + +`/readiness-fix` は、リポジトリで保存されている最新の readiness レポートを取得し、失敗した基準に対して順番に作業を進めるエージェントセッションを開始します。例えば、pre-commit フックの追加、`AGENTS.md` の作成、CI チェックの設定、ドキュメントの改善などの修正を実装します。 + +### 使用方法 -`/readiness-report` の実行後、CLI から直接失敗した基準を自動的に修正できるようになります： +`/readiness-report` を実行したのと同じリポジトリに移動して実行します： + +```bash +droid +> /readiness-fix +``` -1. 評価結果をレビュー -2. 修復したい失敗した基準を選択 -3. droid が修正を実装（例：pre-commit フックの追加、AGENTS.md の作成、ブランチ保護の設定） +実行を絞り込むために、追加の自然言語による指示を渡すこともできます： -これにより、レポートは診断ツールから自動化された改善ワークフローに変わります。 +```bash +> /readiness-fix prioritize style & validation; do not touch CI configuration +``` + +### 期待される動作 + +1. **レポート検索** — コマンドは `git remote get-url origin` からリポジトリを解決し、そのリポジトリに対して保存されている最新の readiness レポートを取得します。 +2. **エージェントセッション** — droid は通常のコーディングセッションと同様に、失敗した基準に対処するための変更を一度に1つずつ計画して適用します。発生する変更をレビューおよび承認できます。 +3. **検証** — 修正が適用された後、`/readiness-report` を再実行してリポジトリを再スコアし、シグナルが改善したことを確認します。 + + + `/readiness-fix` を使用するには、対象リポジトリの readiness レポートが既に生成されている必要があります。事前のレポートが見つからない場合は、まず `/readiness-report` を実行してください。 + + + + `/readiness-fix` は他のエージェント実行と同様に扱ってください：提案された変更をレビューし、テストを実行し、コードベースに適していると判断したものだけをコミットしてください。 + diff --git a/docs/jp/cli/getting-started/overview.mdx b/docs/jp/cli/getting-started/overview.mdx index 4979a816..f6c1e808 100644 --- a/docs/jp/cli/getting-started/overview.mdx +++ b/docs/jp/cli/getting-started/overview.mdx @@ -41,6 +41,16 @@ droid **クイックヒント:** `!`を押すとbashモードに切り替わり、AIの解釈なしでシェルコマンドを直接実行できます。通常モードに戻るには`Esc`を押します。詳しくは[CLIリファレンス](/jp/reference/cli-reference#bash-mode)を参照してください。 +## 主な機能 + +- **Missions**: オーケストレーターが専門のワーカー Droid を編成し、より大きな機能の計画・実装・検証を行うマルチエージェントプロジェクトを起動します。`/missions` で開始するか、`droid exec --mission` でヘッドレス実行できます。[詳細 →](/jp/cli/features/missions) +- **MCP**: Model Context Protocol を通じて droid を外部のツールやデータソースに接続します。`droid mcp add` でサーバーを追加するか、`/mcp` で管理します。[詳細 →](/jp/cli/configuration/mcp) +- **カスタム Droid**: 独自のシステムプロンプト、ツール、モデルを持つ専門サブエージェントを定義し、タスクを委任します。`/droids` から管理できます。[詳細 →](/jp/cli/configuration/custom-droids) +- **Skills**: 再利用可能な手順やドメイン知識をパッケージ化し、droid がオンデマンドで呼び出せるようにします。`/skills` または `/create-skill` でスキルを閲覧・作成します。[詳細 →](/jp/cli/configuration/skills) +- **Hooks**: 特定のツールイベントの前後にシェルコマンドを実行することで、エージェントのライフサイクル周辺の動作を自動化します。`/hooks` で設定します。[詳細 →](/jp/cli/configuration/hooks-guide) +- **Plugins**: マーケットプレイスを通じて配布されるスラッシュコマンド、droid、スキル、フックの導入可能なバンドルで droid を拡張します。`droid plugin install` でインストールするか、`/plugins` で管理します。[詳細 →](/jp/cli/configuration/plugins) +- **Exec モード**: スクリプト、CI/CD パイプライン、自動化のために droid をヘッドレスで実行します。構造化された入出力形式で `droid exec` を使用します。[詳細 →](/jp/cli/droid-exec/overview) + ## `droid` がワークフローにもたらすもの - **エンドツーエンドの機能開発**: 計画から実装、テストまで - Droidは透明性のあるレビューワークフローを通じてあなたのコントロール下を保ちながら、完全な開発ライフサイクルを処理します。 diff --git a/docs/jp/cli/getting-started/quickstart.mdx b/docs/jp/cli/getting-started/quickstart.mdx index 8c9970d6..fc4805df 100644 --- a/docs/jp/cli/getting-started/quickstart.mdx +++ b/docs/jp/cli/getting-started/quickstart.mdx @@ -150,16 +150,20 @@ Droidは Git 操作を対話的で賢いものにします： 日常的に使用する主要な操作は以下の通りです： -| アクション | 実行内容 | 使用方法 | -| ---------------- | ------------------------------ | ------------------------------ | -| メッセージ送信 | タスクまたは質問を送信 | 入力して**Enter**を押す | -| 複数行入力 | より長いプロンプトを記述 | **Shift\+Enter**で改行 | -| 変更を承認 | 提案された修正を受け入れ | TUIで変更を受け入れ | -| 変更を拒否 | 提案された修正を拒否 | TUIで変更を拒否 | -| モード切り替え | モード間を切り替え | **Shift\+Tab** | -| Bashモード | AIの解釈なしでシェルコマンドを直接実行 | 入力が空の状態で`!`を押す；戻るには`Esc` | -| ショートカット表示 | 利用可能なコマンドをすべて表示 | **?**を押す | -| セッション終了 | Droidを終了 | **Ctrl\+C**または`exit`を入力 | +| アクション | 実行内容 | 使用方法 | +| -------------------- | ----------------------------------------------------- | -------------------------------------------- | +| メッセージ送信 | タスクまたは質問を送信 | 入力して**Enter**を押す | +| 複数行入力 | より長いプロンプトを記述 | **Shift\+Enter**で改行 | +| 変更を承認 | 提案された修正を受け入れ | TUIで変更を受け入れ | +| 変更を拒否 | 提案された修正を拒否 | TUIで変更を拒否 | +| モード切り替え | モード間を切り替え | **Shift\+Tab** | +| Bashモード | AIの解釈なしでシェルコマンドを直接実行 | 入力が空の状態で`!`を押す；戻るには`Esc` | +| トランスクリプト表示 | メッセージ詳細を含む詳細なトランスクリプトを切り替え | **Ctrl+O** | +| ミッションコントロール | Mission Control オーバーレイを切り替え（オーケストレーターセッション） | **Ctrl+T** | +| オーバーレイを閉じる | アクティブなオーバーレイまたはメニューを閉じる | **Escape** | +| トランスクリプトをスクロール | 過去のターンを移動 | **Alt+Up** / **Alt+Down** | +| ショートカット表示 | 利用可能なコマンドをすべて表示 | **?**を押す | +| セッション終了 | Droidを終了 | **Ctrl\+C**または`exit`を入力 | @@ -170,6 +174,14 @@ Droidは Git 操作を対話的で賢いものにします： - `/review` - AI搭載コードレビューワークフローを開始（[learn more](/jp/cli/features/code-review)） - `/settings` - Droidの動作、モデル、設定を構成 - `/model` - セッション中にAIモデルを切り替え +- `/sessions` - 過去のセッションを一覧表示し再開 +- `/fork` - 現在のセッションを新しいブランチへフォーク +- `/compress` - 現在のセッションを圧縮してコンテキストを解放 +- `/missions` - Missions メニューを開いてマルチエージェントプロジェクトを起動 +- `/droids` - カスタム Droid（専門サブエージェント）を管理 +- `/skills` - プロンプトベースのスキル（再利用可能な手順）を管理 +- `/hooks` - ライフサイクル自動化のためのツール実行フックを管理 +- `/plugins` - プラグインとマーケットプレイスを管理 - `/mcp` - Model Context Protocol サーバーを管理 - `/account` - ブラウザでFactory アカウント設定を開く - `/billing` - 請求設定を表示・管理 diff --git a/docs/jp/cli/user-guides/become-a-power-user.mdx b/docs/jp/cli/user-guides/become-a-power-user.mdx index 8bc60ad4..d3368fc0 100644 --- a/docs/jp/cli/user-guides/become-a-power-user.mdx +++ b/docs/jp/cli/user-guides/become-a-power-user.mdx @@ -4,7 +4,7 @@ description: IDE連携、スマートな計画、プロジェクト最適化でD keywords: ['power user', 'advanced', 'tips', 'optimization', 'performance', 'productivity', 'efficiency', 'best practices'] --- -Droidをより速く、より賢く、より少ない反復で動作させたいですか？これら4つのパワー機能が、良い結果を卓越した結果に変換します。各テクニックはトークンを節約し、ツール呼び出しを減らし、より良いコードを提供します。 +Droidをより速く、より賢く、より少ない反復で動作させたいですか？このページで紹介するテクニックは、良い結果を卓越した結果に変換します。各テクニックはトークンを節約し、ツール呼び出しを減らし、より良いコードを提供します — まずは4つの基礎的な機能から始め、その後で下記のワークフローブースターを重ねていきましょう。 @@ -146,10 +146,151 @@ Droidが間違いを繰り返したり、何かを2回説明したりするた **重要:** 検証を高速に保ってください。遅いテストはエンドツーエンドの作業を遅くします。 -## 最大の効果を得るための4つ全ての組み合わせ +## キーボードショートカット — TUI をプロのように操る -これらの機能は相乗効果があります。IDE pluginがコンテキストを提供 → Spec Modeがそのコンテキストを使ってより良い計画を立てる → AGENTS.mdが一貫した実装を保証 → Agent readinessが問題を即座にキャッチします。 +TUI には、ほぼすべての一般的な操作のためのショートカットが用意されています。いくつか覚えるだけで、マウスに手を伸ばしたり延々とスクロールしたりする必要がなくなります。 + +| ショートカット | アクション | +| --- | --- | +| `Ctrl+O` | 詳細トランスクリプト表示の切り替え（メッセージ詳細をすべて表示） | +| `Ctrl+T` | Mission Control オーバーレイの切り替え（オーケストレーターセッション） | +| `Ctrl+N` | 利用可能なモデルを順番に切り替え | +| `Ctrl+L` | 自律レベルを順番に切り替え（low / medium / high） | +| `Ctrl+Y` | `/btw` のサイド質問スクロールビューを切り替え | +| `Ctrl+E` | 承認の詳細を切り替え | +| `Alt+Up` / `Alt+Down` | トランスクリプトをターン単位でスクロール | +| `Alt+PageUp` / `Alt+PageDown` | ユーザーのターンのみをジャンプ | +| `Shift+Enter` | プロンプト入力に改行を挿入 | +| `Escape` | アクティブなオーバーレイやメニューを閉じる | +| `!` | 入力が空のときに bash モードを切り替え | + + + 全リストは [CLI リファレンス](/jp/reference/cli-reference#keyboard-shortcuts) を参照してください。 + + +## Bash モード — TUI を離れずに素早くシェルへアクセス + +入力が空の状態で `!` を押すと bash モードに入ります。入力した内容はあなたのシェルで実行され、出力はトランスクリプトに残るため、Droid は次のターンでそれを参照できます — コピー＆ペースト不要です。 + +``` +! git status +! npm test -- --watch=false +``` + +状態の確認、簡単なビルドの実行、Droid に反応してほしい出力の取得などに使えます。`Escape` を押すか、空のまま送信すると bash モードを抜けます。 + +## ワークツリー — 同一リポジトリで並列セッションを実行 + +`--worktree` フラグを使うと、Droid を新しい git worktree 内で起動でき、複数のセッションが同じリポジトリを編集してもお互い干渉しません。`--worktree-dir`（または `worktreeDirectory` 設定）と組み合わせれば、すべての worktree を1か所にまとめられます。 + +```bash +droid --worktree feature-auth +droid --worktree feature-billing +``` + +各セッションはそれぞれ独立したブランチで動くため、並列で実験を走らせ、最良の結果だけをマージできます。 + +## セッション管理 — `/sessions`、`/fork`、`/compress` + +長時間の作業は1つのセッションに閉じ込める必要はありません。これらのコマンドで会話の移動、分岐、整理ができます： + +- `/sessions` — 過去のセッションを一覧表示し、再開する +- `/fork` — 現在のセッションを分岐し、元の場所を失わずに別のアプローチを試す +- `/compress` — コンテキスト上限が近づいたらトランスクリプトをコンパクト化する（`/compact` や `/handoff` でも利用可能） + +``` +/fork +/compress focus on the failing migration +``` + +フォークは「もし〜だったら」の実験に特に強力です。分岐してリスクのあるリファクタリングを試し、うまくいかなければ元のセッションに戻れます。 + +## 速度と反復 — `/fast` + +`/fast` は現在のモデルを高速バリアントに切り替えるので、小さな編集や調査を反復するときにテンポよく進みます。`/fast off` で元に戻せます。 + +``` +/fast +``` + +## コンテキスト管理 — `/context` と `/btw` + +`/context` は、コンテキストウィンドウの内訳をリアルタイムで表示します。システムプロンプト、ファイル、ツール結果、会話のそれぞれに何トークン使われているかが分かるので、コンパクション発動前に膨らみを見つけるのに役立ちます。 + +`/btw` ではサイド質問ができます — Droid は別スクロールバッファ（`Ctrl+Y` で表示）で回答するため、メイントランスクリプトを汚さずに、タスクから集中を逸らさずに調べ物ができます。 + +``` +/context +/btw what does the @decorator pattern in src/auth.ts do? +``` + +両者を組み合わせると、メインセッションを集中状態に保ったまま、横で調査を進められます。 + +## カスタムスラッシュコマンド — `/commands` + +よく使うプロンプトを再利用可能なショートカットとして保存しましょう。`/commands` を実行するとマネージャーが開き、プロジェクトレベルまたはユーザーレベルでカスタムスラッシュコマンドを作成・編集・スコープ設定できます。 + +``` +/commands +``` + +リリースチェックリストを実行する `/ship`、新しいバグをスキャンする `/triage` など、よく入力する内容を何でもコマンド化できます。カスタムコマンドは引数を受け取れるので、他のワークフローとも組み合わせやすいです。 + +## フック — ツール呼び出し前後の自動化 + +`/hooks` を使うと、Droid がツールを実行する前や後に発火するライフサイクルスクリプトを登録できます — pre-commit チェック、監査ログ、自動フォーマッター、危険なシェルコマンドを拒否するガードレールなどに活用できます。 + +``` +/hooks +``` + +フックは設定ファイルに保存され、すべてのセッションに適用されます。プロンプトで毎回繰り返さずにチームの規約を強制するのに最適です。 + +## MCP 連携 — `/mcp` + +Model Context Protocol を使うと、Droid は標準インターフェースを通じて外部ツール（データベース、課題管理、デザインツール、社内サービスなど）と対話できます。サーバーは TUI の `/mcp`、もしくはコマンドラインの `droid mcp add/remove` で管理します。 + +```bash +droid mcp add linear https://mcp.linear.app/sse --type http +``` + +接続後は、Droid がチケットを読んだり、データベースに問い合わせたり、サーバーが提供する任意の機能を呼び出したりできます — カスタム連携を組まずに済みます。 + +## ミッション — 大規模なマルチエージェントプロジェクトの調整 + +複数の機能やファイルにまたがる作業では、`/missions` でミッションに切り替えましょう。Droid が作業を計画し、専門のワーカーエージェントを生成し、各マイルストーンを検証します — 「チャットの中のエージェント」と「計画を実行するエージェントチーム」のギャップを埋める仕組みです。 + +``` +/missions +``` + +`missionModelSettings` でワーカーと検証エージェントのモデルを設定し、`droid exec --mission` でヘッドレス実行できます。完全なガイドは[ミッション](/jp/cli/features/missions)を参照してください。 + +## カスタム Droid — 専門化されたエージェントを必要に応じて + +`/droids` は、独自のシステムプロンプト、ツールセット、モデルを持つサブエージェントのライブラリを管理します。専門知識を1つの Droid に閉じ込めることで（「フロントエンドレビュー担当」「SQL マイグレーション作成」「リリースノート」など）、任意のセッションから呼び出せるようになります。 + +``` +/droids +``` + +自然言語による説明から新しい Droid を生成し、他の設定と同じように反復改善することもできます。詳細は[カスタム Droid](/jp/cli/configuration/custom-droids) を参照してください。 + +## カスタマイズ — サウンド、テーマ、ステータスライン + +TUI を自分の家のような場所にしましょう。`/themes` でカラースキームを切り替え、`/statusline` でカスタムステータスバーを設定でき、`completionSound`、`soundFocusMode`、`subagentSounds` などの設定で重要なイベント（完了、入力待ち、サブエージェントの活動）に音声キューを割り当てられます。 + +``` +/themes +/statusline +``` + +サウンド通知を長時間のミッションと組み合わせれば、状況把握を失わずにターミナルから離れることができます。 + +## すべてを組み合わせる + +これらの機能は相乗効果があります。IDE プラグインと AGENTS.md が Droid に必要なコンテキストと規約を与え、仕様モードと Agent Readiness が初回の試みを正しく保ち、キーボードショートカット、bash モード、`/btw` がキーボードから手を離さずに作業を続けさせ、`/fast`、ワークツリー、ミッション、カスタム Droid が作業そのものをスケールさせます。 - **始めたばかりですか？** まずIDEプラグインをインストールしてください。より良い結果への最短経路です。次にテストコマンドだけを含むAGENTS.mdを追加し、そこから拡張します。 + **始めたばかりですか？** まずは IDE プラグインをインストールしてください — より良い結果への最短経路です。次にテストコマンドを含む AGENTS.md を追加し、3〜4個のショートカットを覚え、そこから少しずつ広げていきましょう。 diff --git a/docs/jp/reference/cli-reference.mdx b/docs/jp/reference/cli-reference.mdx index 5002c75d..b443f48a 100644 --- a/docs/jp/reference/cli-reference.mdx +++ b/docs/jp/reference/cli-reference.mdx @@ -22,16 +22,31 @@ CLIは2つのモードで動作します： ## CLIコマンド -| コマンド | 説明 | 例 | -| :------------------------------- | :---------------------------------- | :---------------------------------------------- | -| `droid` | インタラクティブREPLを開始 | `droid` | -| `droid "query"` | 初期プロンプトでREPLを開始 | `droid "explain this project"` | -| `droid exec "query"` | インタラクティブモードなしでタスクを実行 | `droid exec "summarize src/auth"` | -| `droid exec -f prompt.md` | ファイルからプロンプトを読み込み | `droid exec -f .factory/prompts/review.md` | -| `cat file \| droid exec` | パイプされたコンテンツを処理 | `git diff \| droid exec "draft release notes"` | -| `droid exec -s "query"` | 既存セッションをexecモードで再開 | `droid exec -s session-123 "continue"` | -| `droid exec --list-tools` | 利用可能なツールをリストして終了 | `droid exec --list-tools` | -| `droid update` | CLIを最新バージョンに手動更新 | `droid update` | +| コマンド | 説明 | 例 | +| :----------------------------------- | :--------------------------------------------------------------------- | :--------------------------------------------- | +| `droid` | インタラクティブREPLを開始 | `droid` | +| `droid "query"` | 初期プロンプトでREPLを開始 | `droid "explain this project"` | +| `droid --resume [sessionId]` | セッションを再開（指定がない場合は最後に変更したものを使用）。エイリアス: `-r` | `droid --resume` | +| `droid --fork ` | セッションを fork して新しいコピーで再開 | `droid --fork session-abc123` | +| `droid exec "query"` | インタラクティブモードなしでタスクを実行 | `droid exec "summarize src/auth"` | +| `droid exec -f prompt.md` | ファイルからプロンプトを読み込み | `droid exec -f .factory/prompts/review.md` | +| `cat file \| droid exec` | パイプされたコンテンツを処理 | `git diff \| droid exec "draft release notes"` | +| `droid exec -s "query"` | 既存セッションをexecモードで再開 | `droid exec -s session-123 "continue"` | +| `droid exec --list-tools` | 利用可能なツールをリストして終了 | `droid exec --list-tools` | +| `droid search "query"` | ローカルセッション横断検索（メッセージ、ドキュメント、ツール結果）。エイリアス: `droid find` | `droid search "auth bug"` | +| `droid mcp add ` | MCP サーバーを追加 | `droid mcp add api https://api.example.com/mcp --type http` | +| `droid mcp remove ` | MCP サーバーを削除 | `droid mcp remove linear` | +| `droid plugin install ` | プラグインをインストール。エイリアス: `droid plugin i` | `droid plugin install factory/code-review` | +| `droid plugin uninstall ` | プラグインをアンインストール。エイリアス: `droid plugin remove` | `droid plugin uninstall factory/code-review` | +| `droid plugin update ` | プラグインを最新バージョンに更新 | `droid plugin update factory/code-review` | +| `droid plugin list` | インストール済みのプラグインを一覧表示 | `droid plugin list` | +| `droid plugin marketplace` | プラグインマーケットプレイスを管理 | `droid plugin marketplace` | +| `droid computer register [name]` | このマシンを Bring-Your-Own-Machine (BYOM) コンピューターとして登録 | `droid computer register laptop` | +| `droid computer remove` | このマシンの BYOM 登録を削除 | `droid computer remove` | +| `droid computer list` | 登録済みの BYOM コンピューターを一覧表示 | `droid computer list` | +| `droid computer ssh ` | 登録済みの BYOM コンピューターに SSH 接続 | `droid computer ssh laptop` | +| `droid daemon` | Factory デーモンサーバーを実行 | `droid daemon` | +| `droid update` | CLIを最新バージョンに手動更新 | `droid update` | ## CLIフラグ @@ -48,7 +63,8 @@ CLIは2つのモードで動作します： | `--list-tools` | 利用可能なツールを表示して終了 | `droid exec --list-tools` | | `-o, --output-format ` | 出力形式（`text`、`json`、`stream-json`、`stream-jsonrpc`） | `droid exec -o json "document API"` | | `--input-format ` | 入力形式（マルチターン用の`stream-jsonrpc`） | `droid exec --input-format stream-jsonrpc -o stream-jsonrpc` | -| `-r, --reasoning-effort ` | 推論努力レベルを上書き（`off`、`none`、`low`、`medium`、`high`） | `droid exec -r high "debug flaky test"` | +| `-r, --resume [sessionId]` | 前回のセッションを再開。インタラクティブモードでは `-r` は `--resume`、`droid exec` では `-r` は `--reasoning-effort` にマッピングされます。 | `droid -r` | +| `-r, --reasoning-effort ` | 推論努力レベルを上書き（`off`、`none`、`low`、`medium`、`high`）。`droid exec` では `-r` はこのフラグにマッピングされます。 | `droid exec -r high "debug flaky test"` | | `--spec-model ` | 仕様計画に別の[モデルID](/jp/models)を使用 | `droid exec --spec-model claude-sonnet-4-6` | | `--spec-reasoning-effort ` | specモードの推論努力を上書き | `droid exec --use-spec --spec-reasoning-effort high` | | `--use-spec` | 仕様モードで開始（実行前に計画） | `droid exec --use-spec "add user profiles"` | @@ -57,6 +73,14 @@ CLIは2つのモードで動作します： | `-w, --worktree [name]` | 隔離された [Gitワークツリー](#git-worktrees) でセッションを実行 | `droid --worktree fix-bug` | | `--tag ` | セッションタグ（名前またはJSON、繰り返し可能） | `droid exec --tag code-review` | | `--log-group-id ` | ログフィルタリング用のロググループID | `droid exec --log-group-id grp-123` | +| `--fork ` | 既存セッションを fork して新しいコピーで再開 | `droid exec --fork session-abc123` | +| `--mission` | `droid exec` を [ミッションモード](/jp/cli/features/missions)（マルチエージェントオーケストレーション）で実行 | `droid exec --mission -f mission.md` | +| `--worker-model ` | ミッションのワーカーエージェントが使用するモデル | `droid exec --mission --worker-model claude-sonnet-4-6` | +| `--worker-reasoning-effort ` | ミッションのワーカーエージェントの推論努力（`off`、`none`、`low`、`medium`、`high`） | `droid exec --mission --worker-reasoning-effort medium` | +| `--validator-model ` | ミッションのバリデーターエージェントが使用するモデル | `droid exec --mission --validator-model claude-opus-4-7` | +| `--validator-reasoning-effort ` | ミッションのバリデーターエージェントの推論努力 | `droid exec --mission --validator-reasoning-effort high` | +| `--append-system-prompt ` | システムプロンプトの末尾にカスタムテキストを追加 | `droid --append-system-prompt "Always run tests."` | +| `--append-system-prompt-file ` | システムプロンプトの末尾にファイルの内容を追加 | `droid --append-system-prompt-file .factory/system.md` | | `-v, --version` | CLIバージョンを表示 | `droid -v` | | `-h, --help` | ヘルプ情報を表示 | `droid --help` | @@ -104,6 +128,53 @@ droid exec --auto high "Run tests, commit, and push changes" ## インタラクティブモードの機能 + + +### キーボードショートカット + +インタラクティブREPLは、ナビゲーション、オーバーレイ、入力制御のための豊富なキーボードショートカットをサポートしています： + +| ショートカット | アクション | +| :--------------- | :--------------------------------------------------------------------------------- | +| `Ctrl+C` | 現在の操作をキャンセル / エージェントを中断。すばやく2回押すと終了 | +| `Ctrl+Z` | プロセスをサスペンド（Unixのみ）。`fg` で再開 | +| `Ctrl+O` | 詳細なトランスクリプトビュー（メッセージ詳細）の表示を切り替え | +| `Ctrl+T` | Mission Control オーバーレイを切り替え（オーケストレーターセッションのみ） | +| `Ctrl+P` | ブログ投稿ビューアーを切り替え | +| `Ctrl+N` | 利用可能なモデルを順に切り替え（チャット入力中） | +| `Ctrl+L` | 自律レベルを順に切り替え（チャット入力中） | +| `Ctrl+Y` | `/btw` のスクロールビュー（サイド質問履歴）を切り替え | +| `Ctrl+J` | 変更履歴の表示を切り替え（非表示 / 復元） | +| `Ctrl+E` | 承認の詳細ビューを切り替え | +| `Ctrl+V` | クリップボードから画像を添付として貼り付け | +| `Tab` | 推論努力レベルを順に切り替え（`low` → `medium` → `high` → `off`） | +| `Shift+Tab` | インタラクションモードを順に切り替え（Auto → Spec → Mission） | +| `@` | ファイルパスの自動補完 — `@` を入力するとファイルのあいまい検索が起動 | +| `Up` / `Down` | 入力履歴を移動（過去に送信したメッセージを順に切り替え） | +| `Double Escape` | 2 回目の押下で入力ドラフトをクリア、3 回目の Escape で巻き戻しメニューを開く | +| `?` | ヘルプポップアップを切り替え（入力が空の時） | +| `Ctrl+/` | ヘルプポップアップを切り替え（入力に内容があっても動作） | +| `Ctrl+A` | カーソルを行頭に移動 | +| `Ctrl+W` | カーソルの前の単語を削除 | +| `Ctrl+K` | カーソルから行末まで削除 | +| `Ctrl+U` | カーソルから行頭まで削除 | +| `Ctrl+D` | 添付されたすべての画像をクリア、画像がない場合は次の文字を前方削除 | +| `Ctrl+R` | ハイライト中のセッション名を変更（`/sessions` リストビュー内） | +| `Ctrl+X` | ハイライト中のセッションをアーカイブ（`/sessions` リストビュー内） | +| `Alt+Up` | トランスクリプトを上にスクロール（任意のターンに移動） | +| `Alt+Down` | トランスクリプトを下にスクロール（任意のターンに移動） | +| `Alt+PageUp` | 前のユーザーターンまでトランスクリプトを上にスクロール | +| `Alt+PageDown` | 次のユーザーターンまでトランスクリプトを下にスクロール | +| `Escape` | アクティブなオーバーレイまたはメニューを閉じる | +| `Shift+Enter` | チャット入力に改行を挿入（複数行編集） | +| `!` | [bashモード](#bash-mode) を切り替え（入力が空の時） | + + + `/terminal-setup` を一度実行して、`Shift+Enter` がチャット入力で確実に改行を生成するようターミナルを設定してください。 + + + + ### Bashモード 入力が空の時に`!`を押すとbashモードを切り替えます。bashモードでは、コマンドはAIの解釈なしにシェルで直接実行されます。`git status`の確認や`npm test`の実行など、素早い操作に便利です。 @@ -114,51 +185,74 @@ droid exec --auto high "Run tests, commit, and push changes" bashモードがアクティブの時、プロンプトが`>`から`$`に変わります。 +### Mermaid 図のレンダリング + +Droid は Mermaid 図のコードブロックをターミナル上で直接 ASCII アートとして自動的にレンダリングします — 外部ビューアやブラウザは不要です。応答に対応する種類のフェンス付き ```` ```mermaid ```` ブロックが含まれている場合、図はトランスクリプト内にインラインで描画されます。 + +**対応している図種類:** + +- `flowchart`（および `graph`） +- `sequenceDiagram` +- `stateDiagram` +- `classDiagram` +- `erDiagram` + +未対応の図種類（たとえば `gantt`、`pie`、`mindmap`、`timeline`、`journey`、`gitGraph`）は、生の Mermaid ソースと外部で図を表示するためのリンクの表示にフォールバックします。 + ### スラッシュコマンド `droid`をインタラクティブモードで実行している時に利用できます。プロンプトでコマンドを入力してください： -| コマンド | 説明 | -| :----------------------- | :---------------------------------------------------- | -| `/account` | ブラウザでFactoryアカウント設定を開く | -| `/billing` | 請求設定の表示と管理 | -| `/bg-process` | バックグラウンドプロセスの管理 | -| `/bug [title]` | セッションデータとログを含むバグレポートの作成 | -| `/clear` | 新しいセッションを開始（`/new`のエイリアス） | -| `/commands` | カスタムスラッシュコマンドの管理 | -| `/compress [prompt]` | セッションを圧縮し、要約と共に新しいセッションに移動 | -| `/cost` | トークン使用統計の表示 | -| `/create-skill` | 現在のセッションから再利用可能なスキルを作成 | -| `/droids` | カスタムDroidの管理 | -| `/missions` | Factory Missionsに入る | -| `/favorite` | 現在のセッションをお気に入りにマーク | -| `/fork` | すべてのメッセージを含む現在のセッションを新しいセッションに複製 | -| `/generate_blog` | セマンティックdiffブログ投稿の生成 | -| `/help` | 利用可能なスラッシュコマンドの表示 | -| `/hooks` | ライフサイクルフックの管理 | -| `/ide` | IDE統合の設定 | -| `/install-code-review` | 自動コードレビューの設定 | -| `/login` | Factoryにサインイン | -| `/logout` | Factoryからサインアウト | -| `/mcp` | Model Context Protocolサーバーの管理 | -| `/mission` | Mission Controlを開く | -| `/missions` | 再開するFactory Missionsの一覧と選択 | -| `/model` | セッション中にAIモデルを切り替え | -| `/new` | 新しいセッションを開始 | -| `/plugins` | プラグインとマーケットプレイスの管理 | -| `/quit` | droidを終了（エイリアス: `exit`、またはCtrl+Cを押す） | -| `/readiness-report` | 準備状況レポートの生成 | -| `/rename` | 現在のセッション名を変更 | -| `/review` | AI支援によるコードレビューワークフローの開始 | -| `/rewind-conversation` | セッション内の最近の変更を取り消し | -| `/sessions` | 過去のセッションの一覧と選択 | -| `/settings` | アプリケーション設定の構成 | -| `/share` | 組織とセッションを共有 | -| `/skills` | スキルの管理と呼び出し | -| `/status` | 現在のDroidの状態と設定を表示 | -| `/statusline` | カスタムステータスラインの設定 | -| `/terminal-setup` | Shift+Enter用のターミナルキーバインドの設定 | -| `/wrapped` | Droidの使用統計を表示 | +| コマンド | 説明 | +| :----------------------------- | :------------------------------------------------------------------ | +| `/account` | ブラウザでFactoryアカウント設定を開く | +| `/billing` | 請求設定の表示と管理 | +| `/btw ` | メイントランスクリプトを汚さずにサイド質問を行う | +| `/bug [title]` | セッションデータとログを含むバグレポートの作成 | +| `/clear` | 新しいセッションを開始（`/new`のエイリアス） | +| `/commands` | カスタムスラッシュコマンドの管理 | +| `/compress [prompt]` | セッションを圧縮し、要約と共に新しいセッションに移動 | +| `/context` | プログレスバー付きでコンテキストウィンドウの使用状況を表示 | +| `/copy` | プロンプト、応答、ターン範囲、またはセッションIDをコピー | +| `/cost` | 使用統計の表示 | +| `/create-skill` | 現在のセッションから再利用可能なスキルを作成 | +| `/cwd ` | セッションの作業ディレクトリを変更 | +| `/diagnostics` | 設定の構成エラーを表示 | +| `/droids` | カスタムDroidの管理 | +| `/missions` | Mission モードに入る | +| `/fast` | 現在のモデルで fast モードを有効化（無効化は `/fast off`） | +| `/favorite` | 現在のセッションをお気に入りにマーク | +| `/fork` | すべてのメッセージを含む現在のセッションを新しいセッションに複製 | +| `/generate_blog` | セマンティックdiffブログ投稿の生成 | +| `/help` | 利用可能なスラッシュコマンドの表示 | +| `/hooks` | ライフサイクルフックの管理 | +| `/ide` | IDE統合の設定 | +| `/install-code-review` | 自動コードレビューの設定 | +| `/install-slack-app` | Slack 連携をインストール / 接続 | +| `/language ` | TUI 表示言語を切り替え | +| `/limits` | トークン使用上限と超過時の挙動を管理 | +| `/login` | Factoryにサインイン | +| `/logout` | Factoryからサインアウト | +| `/mcp` | Model Context Protocolサーバーの管理 | +| `/model` | セッション中にAIモデルを切り替え | +| `/new` | 新しいセッションを開始 | +| `/plugins` | プラグインとマーケットプレイスの管理 | +| `/quit` | droidを終了（エイリアス: `exit`、またはCtrl+Cを押す） | +| `/readiness-fix` | 最新レポートで失敗しているエージェント準備シグナルを修正 | +| `/readiness-report` | 準備状況レポートの生成 | +| `/rename` | 現在のセッション名を変更 | +| `/review` | AI支援によるコードレビューワークフローの開始 | +| `/rewind-conversation` | セッション内の最近の変更を取り消し | +| `/sessions` | 過去のセッションの一覧と選択 | +| `/settings` | アプリケーション設定の構成 | +| `/setup-incident-response` | インシデント対応チャンネル向けの Slack 自動実行をセットアップ | +| `/share` | 組織とセッションを共有 | +| `/skills` | スキルの管理と呼び出し | +| `/stats [period]` | 使用統計の表示（相対期間、日付範囲に対応） | +| `/status` | 現在のDroidの状態と設定を表示 | +| `/statusline` | カスタムステータスラインの設定 | +| `/terminal-setup` | Shift+Enter用のターミナルキーバインドの設定 | +| `/themes` | カラーテーマを選択 | スラッシュコマンドの詳細については、[インタラクティブモードのドキュメント](/jp/cli/getting-started/quickstart#useful-slash-commands)をご覧ください。 @@ -206,6 +300,41 @@ droid --worktree feature-b & インストールされていない場合があるため、ビルドやテストがモジュール不足で失敗したときはセットアップしてください。 +### サブコマンドのフラグ + +上記のグローバルフラグに加えて、いくつかの `droid` サブコマンドは独自のフラグを受け付けます。 + +#### `droid search` のフラグ + +| フラグ | 説明 | 例 | +| :-------------------- | :--------------------------------------------------------------------------------- | :--------------------------------------- | +| `--kind ` | エントリ種別でフィルタ: `message_text`、`document`、`tool_use`、`tool_result`、または `all` | `droid search "auth" --kind document` | +| `--limit-sessions ` | 返却するセッションの最大数 | `droid search "auth" --limit-sessions 5` | +| `--limit-hits ` | セッション・種別ごとに返すマッチの最大数 | `droid search "auth" --limit-hits 3` | +| `--context-chars ` | 各マッチ周辺に表示するコンテキストの文字数 | `droid search "auth" --context-chars 200`| +| `--json` | 結果を JSON で出力 | `droid search "auth" --json` | +| `--reindex` | 検索キャッシュを破棄してローカルインデックスを再構築 | `droid search "auth" --reindex` | + +#### `droid mcp add` のフラグ + +| フラグ | 説明 | 例 | +| :------------------------- | :---------------------------------------------------------------------------------- | :--------------------------------------------------------------- | +| `--type ` | サーバーのトランスポート: `http`（ストリーミングHTTP）または `stdio`（ローカル） | `droid mcp add api https://api.example.com/mcp --type http` | +| `--env ` | stdio サーバー用の環境変数を設定（繰り返し可能） | `droid mcp add gh "gh-mcp" --type stdio --env GH_TOKEN=$GH_TOKEN`| +| `--header ` | リモートサーバー用の HTTP ヘッダーを追加（繰り返し可能） | `droid mcp add api https://api.example.com/mcp --type http --header "Authorization: Bearer $TOKEN"` | + +#### `droid plugin` のフラグ + +| フラグ | 説明 | 例 | +| :-------------------- | :----------------------------------------------------------------- | :--------------------------------------------------------- | +| `-s, --scope ` | インストール範囲: `user`（デフォルト）または `project` | `droid plugin install factory/code-review --scope project` | + +#### `droid computer register` のフラグ + +| フラグ | 説明 | 例 | +| :----------- | :-------------------------------------------------------- | :----------------------------------- | +| `-y, --yes` | 対話プロンプトをスキップして登録のデフォルトを受け入れる | `droid computer register laptop -y` | + ### MCPコマンドリファレンス `/mcp`スラッシュコマンドは、MCPサーバーの閲覧と管理のためのインタラクティブマネージャーUIを開きます。 diff --git a/docs/reference/cli-reference.mdx b/docs/reference/cli-reference.mdx index 62aba3ef..fa51046a 100644 --- a/docs/reference/cli-reference.mdx +++ b/docs/reference/cli-reference.mdx @@ -24,16 +24,31 @@ The Droid CLI operates in two modes: ## Droid CLI commands -| Command | Description | Example | -| :--------------------------- | :---------------------------------------- | :--------------------------------------------- | -| `droid` | Start interactive REPL | `droid` | -| `droid "query"` | Start REPL with initial prompt | `droid "explain this project"` | -| `droid exec "query"` | Execute task without interactive mode | `droid exec "summarize src/auth"` | -| `droid exec -f prompt.md` | Load prompt from file | `droid exec -f .factory/prompts/review.md` | -| `cat file \| droid exec` | Process piped content | `git diff \| droid exec "draft release notes"` | -| `droid exec -s "query"` | Resume existing session in exec mode | `droid exec -s session-123 "continue"` | -| `droid exec --list-tools` | List available tools, then exit | `droid exec --list-tools` | -| `droid update` | Manually update the CLI to latest version | `droid update` | +| Command | Description | Example | +| :----------------------------------- | :--------------------------------------------------------------------- | :--------------------------------------------- | +| `droid` | Start interactive REPL | `droid` | +| `droid "query"` | Start REPL with initial prompt | `droid "explain this project"` | +| `droid --resume [sessionId]` | Resume a session (defaults to last modified). Alias: `-r` | `droid --resume` | +| `droid --fork ` | Fork and resume a session in a new copy | `droid --fork session-abc123` | +| `droid exec "query"` | Execute task without interactive mode | `droid exec "summarize src/auth"` | +| `droid exec -f prompt.md` | Load prompt from file | `droid exec -f .factory/prompts/review.md` | +| `cat file \| droid exec` | Process piped content | `git diff \| droid exec "draft release notes"` | +| `droid exec -s "query"` | Resume existing session in exec mode | `droid exec -s session-123 "continue"` | +| `droid exec --list-tools` | List available tools, then exit | `droid exec --list-tools` | +| `droid search "query"` | Search across local sessions (messages, documents, tool results). Alias: `droid find` | `droid search "auth bug"` | +| `droid mcp add ` | Add an MCP server | `droid mcp add api https://api.example.com/mcp --type http` | +| `droid mcp remove ` | Remove an MCP server | `droid mcp remove linear` | +| `droid plugin install ` | Install a plugin. Alias: `droid plugin i` | `droid plugin install factory/code-review` | +| `droid plugin uninstall ` | Uninstall a plugin. Alias: `droid plugin remove` | `droid plugin uninstall factory/code-review` | +| `droid plugin update ` | Update a plugin to the latest version | `droid plugin update factory/code-review` | +| `droid plugin list` | List installed plugins | `droid plugin list` | +| `droid plugin marketplace` | Manage plugin marketplaces | `droid plugin marketplace` | +| `droid computer register [name]` | Register this machine as a Bring-Your-Own-Machine (BYOM) computer | `droid computer register laptop` | +| `droid computer remove` | Remove this machine's BYOM registration | `droid computer remove` | +| `droid computer list` | List registered BYOM computers | `droid computer list` | +| `droid computer ssh ` | SSH into a registered BYOM computer | `droid computer ssh laptop` | +| `droid daemon` | Run the Factory daemon server | `droid daemon` | +| `droid update` | Manually update the CLI to latest version | `droid update` | ## Droid CLI flags @@ -50,7 +65,8 @@ Customize droid's behavior with command-line flags: | `--list-tools` | Print available tools and exit | `droid exec --list-tools` | | `-o, --output-format ` | Output format (`text`, `json`, `stream-json`, `stream-jsonrpc`) | `droid exec -o json "document API"` | | `--input-format ` | Input format (`stream-jsonrpc` for multi-turn) | `droid exec --input-format stream-jsonrpc -o stream-jsonrpc` | -| `-r, --reasoning-effort ` | Override reasoning effort (`off`, `none`, `low`, `medium`, `high`) | `droid exec -r high "debug flaky test"` | +| `-r, --resume [sessionId]` | Resume a previous session. In interactive mode, `-r` is `--resume`; in `droid exec`, `-r` is `--reasoning-effort`. | `droid -r` | +| `-r, --reasoning-effort ` | Override reasoning effort (`off`, `none`, `low`, `medium`, `high`). In `droid exec`, `-r` maps to this flag. | `droid exec -r high "debug flaky test"` | | `--spec-model ` | Use a different [model ID](/models) for specification planning | `droid exec --spec-model claude-sonnet-4-6` | | `--spec-reasoning-effort ` | Override reasoning effort for spec mode | `droid exec --use-spec --spec-reasoning-effort high` | | `--use-spec` | Start in specification mode (plan before executing) | `droid exec --use-spec "add user profiles"` | @@ -59,6 +75,14 @@ Customize droid's behavior with command-line flags: | `-w, --worktree [name]` | Run the session in an isolated [git worktree](#git-worktrees) | `droid --worktree fix-bug` | | `--tag ` | Session tag (name or JSON, repeatable) | `droid exec --tag code-review` | | `--log-group-id ` | Log group ID for filtering logs | `droid exec --log-group-id grp-123` | +| `--fork ` | Fork and resume an existing session into a new copy | `droid exec --fork session-abc123` | +| `--mission` | Run `droid exec` in [mission mode](/cli/features/missions) (multi-agent orchestration) | `droid exec --mission -f mission.md` | +| `--worker-model ` | Model used for mission worker agents | `droid exec --mission --worker-model claude-sonnet-4-6` | +| `--worker-reasoning-effort ` | Reasoning effort for mission worker agents (`off`, `none`, `low`, `medium`, `high`) | `droid exec --mission --worker-reasoning-effort medium` | +| `--validator-model ` | Model used for mission validator agents | `droid exec --mission --validator-model claude-opus-4-7` | +| `--validator-reasoning-effort ` | Reasoning effort for mission validator agents | `droid exec --mission --validator-reasoning-effort high` | +| `--append-system-prompt ` | Append custom text to the end of the system prompt | `droid --append-system-prompt "Always run tests."` | +| `--append-system-prompt-file ` | Append the contents of a file to the end of the system prompt | `droid --append-system-prompt-file .factory/system.md` | | `-v, --version` | Display CLI version | `droid -v` | | `-h, --help` | Show help information | `droid --help` | @@ -108,6 +132,50 @@ See [Choosing Your Model](/cli/user-guides/choosing-your-model) for detailed gui ## Interactive mode features +### Keyboard shortcuts + +The interactive REPL supports a rich set of keyboard shortcuts for navigation, overlays, and input control: + +| Shortcut | Action | +| :---------------- | :------------------------------------------------------------------------------ | +| `Ctrl+C` | Cancel the current operation / interrupt the agent. Press twice quickly to exit | +| `Ctrl+Z` | Suspend the process (Unix only). Resume with `fg` | +| `Ctrl+O` | Toggle the detailed transcript view (full message details) | +| `Ctrl+T` | Toggle the Mission Control overlay (orchestrator sessions only) | +| `Ctrl+P` | Toggle the blog post viewer | +| `Ctrl+N` | Cycle through available models (when typing in chat input) | +| `Ctrl+L` | Cycle through autonomy levels (when typing in chat input) | +| `Ctrl+Y` | Toggle the `/btw` scroll view (side-question history) | +| `Ctrl+J` | Toggle the changelog display (dismiss / restore) | +| `Ctrl+E` | Toggle the approval details view | +| `Ctrl+V` | Paste an image from the clipboard as an attachment | +| `Tab` | Cycle reasoning effort (`low` → `medium` → `high` → `off`) | +| `Shift+Tab` | Cycle interaction modes (Auto → Spec → Mission) | +| `@` | File path autocomplete — typing `@` triggers fuzzy file search | +| `Up` / `Down` | Navigate input history (cycle through previously submitted messages) | +| `Double Escape` | Second press clears the input draft; a third Escape opens the rewind menu | +| `?` | Toggle the help popup (when the input is empty) | +| `Ctrl+/` | Toggle the help popup (works even when the input has content) | +| `Ctrl+A` | Move the cursor to the start of the line | +| `Ctrl+W` | Delete the word before the cursor | +| `Ctrl+K` | Delete from the cursor to the end of the line | +| `Ctrl+U` | Delete from the cursor to the start of the line | +| `Ctrl+D` | Clear all attached images, or forward-delete the next character if none attached | +| `Ctrl+R` | Rename the highlighted session (in the `/sessions` list view) | +| `Ctrl+X` | Archive the highlighted session (in the `/sessions` list view) | +| `Alt+Up` | Scroll the transcript up (navigate any turn) | +| `Alt+Down` | Scroll the transcript down (navigate any turn) | +| `Alt+PageUp` | Scroll the transcript up to the previous user turn | +| `Alt+PageDown` | Scroll the transcript down to the next user turn | +| `Escape` | Close the active overlay or menu | +| `Shift+Enter` | Insert a newline in the chat input (multiline editing) | +| `!` | Toggle [bash mode](#bash-mode) (when the input is empty) | + + + Run `/terminal-setup` once to configure your terminal so `Shift+Enter` reliably produces a newline + in the chat input. + + ### Bash mode Press `!` when the input is empty to toggle bash mode. In bash mode, commands execute directly in your shell without AI interpretation—useful for quick operations like checking `git status` or running `npm test`. @@ -118,49 +186,74 @@ Press `!` when the input is empty to toggle bash mode. In bash mode, commands ex The prompt changes from `>` to `$` when bash mode is active. +### Mermaid diagram rendering + +Droid automatically renders Mermaid diagram code blocks as ASCII art directly in the terminal — no external viewer or browser required. When a response contains a fenced ```` ```mermaid ```` block of a supported diagram type, the diagram is drawn inline in the transcript. + +**Supported diagram types:** + +- `flowchart` (and `graph`) +- `sequenceDiagram` +- `stateDiagram` +- `classDiagram` +- `erDiagram` + +Unsupported diagram types (for example `gantt`, `pie`, `mindmap`, `timeline`, `journey`, `gitGraph`) fall back to displaying the raw Mermaid source and a link to view the diagram externally. + ### Slash commands Available when running `droid` in interactive mode. Type the command at the prompt: -| Command | Description | -| :--------------------- | :------------------------------------------------------------- | -| `/account` | Open Factory account settings in browser | -| `/billing` | View and manage billing settings | -| `/bg-process` | Manage background processes | -| `/bug [title]` | Create a bug report with session data and logs | -| `/clear` | Start a new session (alias for `/new`) | -| `/commands` | Manage custom slash commands | -| `/compress [prompt]` | Compress session and move to new one with summary | -| `/cost` | Show usage statistics | -| `/create-skill` | Create a reusable skill from current session | -| `/droids` | Manage custom droids | -| `/missions` | Enter Mission Mode | -| `/favorite` | Mark current session as a favorite | -| `/fork` | Duplicate current session with all messages into a new session | -| `/generate_blog` | Generate semantic diff blog post | -| `/help` | Show available slash commands | -| `/hooks` | Manage lifecycle hooks | -| `/ide` | Configure IDE integrations | -| `/install-code-review` | Set up automated code review | -| `/login` | Sign in to Factory | -| `/logout` | Sign out of Factory | -| `/mcp` | Manage Model Context Protocol servers | -| `/model` | Switch AI model mid-session | -| `/new` | Start a new session | -| `/plugins` | Manage plugins and marketplaces | -| `/quit` | Exit droid (alias: `exit`, or press Ctrl+C) | -| `/readiness-report` | Generate readiness report | -| `/rename` | Rename current session | -| `/review` | Start AI-powered code review workflow | -| `/rewind-conversation` | Undo recent changes in the session | -| `/sessions` | List and select previous sessions | -| `/settings` | Configure application settings | -| `/share` | Share session with organization | -| `/skills` | Manage and invoke skills | -| `/status` | Show current droid status and configuration | -| `/statusline` | Configure custom status line | -| `/terminal-setup` | Configure terminal keybindings for Shift+Enter | -| `/wrapped` | Show Droid usage statistics | +| Command | Description | +| :---------------------------- | :------------------------------------------------------------- | +| `/account` | Open Factory account settings in browser | +| `/billing` | View and manage billing settings | +| `/btw ` | Ask a side question without polluting the main transcript | +| `/bug [title]` | Create a bug report with session data and logs | +| `/clear` | Start a new session (alias for `/new`) | +| `/commands` | Manage custom slash commands | +| `/compress [prompt]` | Compress session and move to new one with summary | +| `/context` | Show context window usage breakdown with progress bar | +| `/copy` | Copy prompts, responses, turn ranges, or session ID | +| `/cost` | Show usage statistics | +| `/create-skill` | Create a reusable skill from current session | +| `/cwd ` | Change session working directory | +| `/diagnostics` | Show settings configuration errors | +| `/droids` | Manage custom droids | +| `/missions` | Enter Mission Mode | +| `/fast` | Enable fast mode for current model (`/fast off` to disable) | +| `/favorite` | Mark current session as a favorite | +| `/fork` | Duplicate current session with all messages into a new session | +| `/generate_blog` | Generate semantic diff blog post | +| `/help` | Show available slash commands | +| `/hooks` | Manage lifecycle hooks | +| `/ide` | Configure IDE integrations | +| `/install-code-review` | Set up automated code review | +| `/install-slack-app` | Install/connect Slack integration | +| `/language ` | Switch TUI display language | +| `/limits` | Manage token usage limits and overage preferences | +| `/login` | Sign in to Factory | +| `/logout` | Sign out of Factory | +| `/mcp` | Manage Model Context Protocol servers | +| `/model` | Switch AI model mid-session | +| `/new` | Start a new session | +| `/plugins` | Manage plugins and marketplaces | +| `/quit` | Exit droid (alias: `exit`, or press Ctrl+C) | +| `/readiness-fix` | Fix failing agent readiness signals from latest report | +| `/readiness-report` | Generate readiness report | +| `/rename` | Rename current session | +| `/review` | Start AI-powered code review workflow | +| `/rewind-conversation` | Undo recent changes in the session | +| `/sessions` | List and select previous sessions | +| `/settings` | Configure application settings | +| `/setup-incident-response` | Set up Slack auto-run for incident-response channel | +| `/share` | Share session with organization | +| `/skills` | Manage and invoke skills | +| `/stats [period]` | Show usage statistics (supports relative periods, date ranges) | +| `/status` | Show current droid status and configuration | +| `/statusline` | Configure custom status line | +| `/terminal-setup` | Configure terminal keybindings for Shift+Enter | +| `/themes` | Choose a color theme | For detailed information on slash commands, see the [interactive mode documentation](/cli/getting-started/quickstart#useful-slash-commands). @@ -206,6 +299,41 @@ droid --worktree feature-b & builds or tests fail with missing-module errors. +### Subcommand flags + +In addition to the global flags above, several `droid` subcommands accept their own flags. + +#### `droid search` flags + +| Flag | Description | Example | +| :-------------------- | :----------------------------------------------------------------------- | :--------------------------------------- | +| `--kind ` | Filter by entry kind: `message_text`, `document`, `tool_use`, `tool_result`, or `all` | `droid search "auth" --kind document` | +| `--limit-sessions ` | Maximum number of sessions to return | `droid search "auth" --limit-sessions 5` | +| `--limit-hits ` | Maximum number of matches per kind per session | `droid search "auth" --limit-hits 3` | +| `--context-chars ` | Number of characters of context shown around each match | `droid search "auth" --context-chars 200`| +| `--json` | Emit results as JSON | `droid search "auth" --json` | +| `--reindex` | Drop the search cache and rebuild the local index | `droid search "auth" --reindex` | + +#### `droid mcp add` flags + +| Flag | Description | Example | +| :------------------------- | :----------------------------------------------------------------------- | :--------------------------------------------------------------- | +| `--type ` | Server transport: `http` (streamable HTTP) or `stdio` (local) | `droid mcp add api https://api.example.com/mcp --type http` | +| `--env ` | Set an environment variable for a stdio server (repeatable) | `droid mcp add gh "gh-mcp" --type stdio --env GH_TOKEN=$GH_TOKEN`| +| `--header ` | Add an HTTP header for a remote server (repeatable) | `droid mcp add api https://api.example.com/mcp --type http --header "Authorization: Bearer $TOKEN"` | + +#### `droid plugin` flags + +| Flag | Description | Example | +| :-------------------- | :----------------------------------------------------------------------- | :------------------------------------------------------- | +| `-s, --scope ` | Installation scope: `user` (default) or `project` | `droid plugin install factory/code-review --scope project` | + +#### `droid computer register` flags + +| Flag | Description | Example | +| :----------- | :------------------------------------------------------- | :----------------------------------- | +| `-y, --yes` | Skip interactive prompts and accept registration defaults | `droid computer register laptop -y` | + ### MCP command reference The `/mcp` slash command opens an interactive manager UI for browsing and managing MCP servers.