# Dropstone Documentation — Complete Reference # https://docs.dropstone.io # Generated from source. Do not hand-edit; run scripts/generate-llms.mjs. ============================================================================== # Welcome to Dropstone URL: https://docs.dropstone.io/getting-started/welcome Description: Dropstone is an agentic coding tool that lives in your terminal. It reads your codebase, makes coordinated edits across files, runs commands, and explains its reasoning as it works. ============================================================================== Dropstone running inside a terminal You describe what you want, and Dropstone reads the relevant code, plans the change, edits files, runs commands, and explains what it did. It works on real projects, not toy snippets, and stays grounded in the code you already have. This page gives you the shape of the product. The [Quick Start](./quick-start) walks you through installing it and shipping your first change. ## Install in seconds Homebrew (recommended): ```bash brew tap blankline-org/dropstone-cli brew install dropstone ``` Or the install script: ```bash curl -fsSL https://dropstone.io/install | bash ``` Then jump into any project: ```bash cd /path/to/your/project dropstone ``` ```bash curl -fsSL https://dropstone.io/install | bash ``` Drops a single `dropstone` binary on your PATH. No Node, no runtime dependencies. ```bash cd /path/to/your/project dropstone ``` PowerShell (recommended): ```powershell irm https://dropstone.io/install.ps1 | iex ``` Or from CMD: ```bash curl -fsSL https://dropstone.io/install.cmd -o install.cmd && install.cmd ``` Then: ```powershell cd C:\path\to\your\project dropstone ``` For a richer terminal experience on Windows, we recommend [WSL](../cli/windows-wsl) plus the Linux one-liner. Verify the install with `dropstone --version`. On first launch you will be prompted to sign in; full sign-in details are on the [Quick Start](./quick-start) page. ## What you can do

Understand a codebase

Ask how authentication flows through the system, where a bug could be hiding, or how a module is wired together. Dropstone reads files on demand and answers with citations to the actual code.

Build features and fix bugs

Describe the change in plain language. Dropstone proposes a plan, edits across files, and shows diffs before anything lands.

Run, test, and verify

Type checks, tests, and lints run automatically when they exist. Failures loop back into the plan so the result is green by the time you read it.

Create commits and pull requests

Generate conventional commit messages, push branches, and open PRs through the GitHub or GitLab integration. Code review summaries included.

Connect your tools with MCP

Wire in databases, internal APIs, ticketing systems, or any Model Context Protocol server. Dropstone treats them like first-class tools.

Customize with rules and skills

Drop an AGENTS.md at the repo root to teach Dropstone your conventions. Package reusable workflows as skills.
## Compose with the shell Dropstone is a Unix citizen. The interactive session is the default surface, but every capability is available from a one-shot invocation, which makes it scriptable in CI, pre-commit hooks, and your own workflows. ```bash # One-shot: ask a question and exit dropstone run "Explain how the auth middleware works" # Pipe a file in dropstone run "Find security issues" < src/auth.ts # Use it in a shell pipeline git diff main | dropstone run "Write a PR description for this diff" # Drive it from CI without a TTY dropstone run --json "Generate release notes from the last 20 commits" ``` ## How it works Dropstone runs as a single binary in your terminal. Nothing to configure, no runtime to install — you start it inside a project and it operates on the files in your working directory. If you would rather have it beside your code as a panel, there is also [Dropstone for VS Code](../cli/vscode). Each turn follows the same loop: No special syntax. "Add a /healthz endpoint that returns build info" is enough. It reads files, greps for symbols, and inspects structure until it has enough to act. Edits are shown as diffs. Shell commands ask for permission unless you have whitelisted them. Type checks, tests, and lints run automatically when they exist. Failures loop back into the plan. The whole interaction stays in your terminal. Your code is never sent anywhere except to Dropstone's own inference, which is operated under a no-retention, no-training policy. See the [Trust page](https://dropstone.io/trust) for details. ## Use Dropstone everywhere | I want to… | Best option | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Start an interactive coding session | Run `dropstone` in your project directory | | Ask a one-off question without a session | `dropstone run "..."` or pipe a file in with `<` | | Resume the last session | `dropstone --continue` (or `dropstone -c`) | | Wire in a custom tool or internal API | [MCP Servers](../cli/mcp-servers) | | Teach Dropstone your repo conventions | Drop an [`AGENTS.md`](../cli/rules) at the repo root | | Package a reusable workflow | [Skills](../cli/skills) and [Plugins](../cli/plugins) | | Use Dropstone in CI or pre-commit | `dropstone run` with `--json` and the [permissions](../cli/permissions) model | | Pick the right model tier for the task | [Models](../cli/models) (Fast / Pro / Heavy) | | Run inside a sandbox or restricted shell | [Permissions](../cli/permissions) | ## Built around three model tiers You pick the model that fits the work. All three are hosted on US infrastructure and tuned for coding.
Fast

Dropstone Fast

Quick edits, scaffolding, single-file refactors, and conversational debugging. Sub-second first token. The default tier for new sessions.
{/* flex-wrap + ml-auto on the badge means the chip drops to a new line when the localized "Recommended" label is too long (e.g. Tamil "பரிந்துரைக்கப்பட்டது") instead of overlapping the next card. whitespace-nowrap keeps the chip text on one line; no uppercase transform so non-Latin scripts don't get widened further. */}
Pro Recommended

Dropstone Pro

Multi-file refactors, cross-cutting changes, and tasks that need broader reasoning. Switch with /effort high.
Heavy

Dropstone Heavy

Architecture decisions, large migrations, and difficult debugging. Deepest reasoning, longest thinking budget. Switch with /effort xhigh.
You do not need to think about model selection up front. Start in Fast and use /effort from inside Dropstone to step up when a task needs more depth. ## Where to go next The [Quickstart](./quick-start) covers install, sign-in, and your first task. [Models](../cli/models) goes deeper on Fast, Pro, and Heavy, and when to reach for each. [Configuration](../cli/config) covers global and per-project settings; [Permissions](../cli/permissions) and [Keybindings](../cli/keybinds) cover the rest. The [Changelog](./changelog) lists every release with the user-visible changes. Once you are set up, the [CLI reference](../cli/cli) and the [slash commands guide](../cli/commands) are the two pages you will come back to most. ---
Building an agent or LLM app that needs to read these docs? Point it at /llms.txt for a site index, or /llms-full.txt for the full corpus in one file.
============================================================================== # Quickstart URL: https://docs.dropstone.io/getting-started/quick-start Description: Install Dropstone, sign in, and ship your first change in under five minutes. This guide gets you from zero to a working agent loop. ============================================================================== By the end of this guide you will have Dropstone installed, signed in, and producing real edits in a project of your choice. ## Before you begin You need: - A terminal or command prompt - A project on disk to point Dropstone at (any language, any size) - A Dropstone account, which you can create at [dropstone.io](https://dropstone.io) ## Step 1: Install Dropstone Pick the install path for your platform. Homebrew (recommended): ```bash brew tap blankline-org/dropstone-cli brew install dropstone ``` Or the install script: ```bash curl -fsSL https://dropstone.io/install | bash ``` Both methods install a single `dropstone` binary on your PATH. No Node, no runtime dependencies. ```bash curl -fsSL https://dropstone.io/install | bash ``` Drops a single `dropstone` binary on your PATH. Works on Debian, Ubuntu, Fedora, RHEL, Alpine, and Arch. Package manager support (apt, dnf, apk) is on the roadmap. PowerShell (recommended): ```powershell irm https://dropstone.io/install.ps1 | iex ``` From CMD: ```bash curl -fsSL https://dropstone.io/install.cmd -o install.cmd && install.cmd ``` For the best terminal experience on Windows, install [WSL](../cli/windows-wsl) and use the Linux one-liner inside it. The native Windows binary works fine for everyday use; WSL just gives you the same shell experience as macOS and Linux. Verify the install: ```bash dropstone --version ``` You should see a version number (the current release is 1.0.8). The binary self-updates in the background, so you stay current without re-running the installer. ## Step 2: Sign in Move into any project directory and start Dropstone: ```bash cd /path/to/your/project dropstone ``` On first launch you will be prompted to sign in. Two options: 1. **Continue in browser** (recommended). Opens [dropstone.io/login](https://dropstone.io/login), signs you in, and hands the token back to the CLI automatically. Uses PKCE so the token never appears in your browser URL bar. 2. **Paste a token**. For SSH or headless sessions. Get a token at [dropstone.io/account](https://dropstone.io/account) and paste it in. Your credentials are stored on disk after the first sign-in. To switch accounts later, run `/login` from inside Dropstone. ## Step 3: Start your first session You are now looking at the Dropstone home screen. Three things to notice: - Your current model tier is shown at the top right (default: **Dropstone Fast**) - The input box at the bottom is where you type - Slash commands begin with `/`. Try `/help` to see them all Type any natural-language prompt to start a session. There is no special syntax to learn. ## Step 4: Ask your first question Let Dropstone tour the project for you. Try one of these: ```text what does this project do? ``` ```text what are the main entry points? ``` ```text explain the folder structure ``` Dropstone will read files on demand and answer with citations to the actual code. You do not need to paste files or write context manually. You can also ask Dropstone about itself: ```text what can you do in this project? ``` ```text what commands have you been given permission to run? ``` ## Step 5: Make your first code change Now describe a small change. For a new project, try something low-risk: ```text add a README with a one-paragraph project description ``` For an existing project: ```text add input validation to the function that creates a user ``` Dropstone will: 1. Find the relevant file 2. Show the proposed change as a diff 3. Ask for your approval before writing 4. Verify the result (type checks, tests, lints if available) Dropstone asks for approval the first time it wants to edit a file or run a shell command. Approve once, and the same operation in the same session runs without re-prompting. Use `/permissions` to view or revoke what you have allowed. ## Step 6: Work with git Dropstone treats git as a first-class tool: ```text what files have I changed? ``` ```text commit my changes with a descriptive message ``` ```text create a branch called feature/health-endpoint and switch to it ``` ```text show the last five commits ``` ```text help me resolve the merge conflict in src/auth.ts ``` For PR-level workflows (opening pull requests, generating PR descriptions, posting review comments), see [GitHub integration](../cli/github). ## Step 7: Fix a bug or add a feature Describe what you want in plain language. Dropstone will locate the code, understand the context, implement the change, and verify it. ```text there is a bug where empty search queries return all results - fix it ``` ```text add a /healthz endpoint to the API server that returns build info ``` ```text the login form crashes when the email is missing - figure out why and fix it ``` If the task spans several files, Dropstone will write a short plan and execute it step by step. You can press `Esc` at any point to interrupt and steer. ## Step 8: Try other common workflows A few patterns Dropstone is good at: **Refactor** ```text refactor the auth module to use async/await instead of callbacks ``` **Write tests** ```text write unit tests for the calculator functions ``` **Code review** ```text review my staged changes and flag anything risky ``` **Documentation** ```text update the README install instructions to include the WSL path ``` Talk to Dropstone like a teammate. Describe what you want to achieve, not the exact steps to get there. The agent is best at planning when you leave the implementation choices to it. ## Essential commands The handful of commands you will actually use: | Command | What it does | Example | | ------------------------ | ----------------------------------------------------- | ------------------------------------ | | `dropstone` | Start an interactive session in the current directory | `dropstone` | | `dropstone run "task"` | Run a one-off task and exit | `dropstone run "explain auth.ts"` | | `dropstone -c` | Continue the last session in this directory | `dropstone -c` | | `dropstone --session ID` | Resume a specific session by id | `dropstone --session 7f3a...` | | `/help` | Show all slash commands | inside a session | | `/effort` | Switch model tier for this session | `/effort high` | | `/clear` | Clear the current conversation | inside a session | | `/login` | Switch accounts | inside a session | | `exit` or `Ctrl+D` | Exit Dropstone | | The full reference is on the [CLI](../cli/cli) and [slash commands](../cli/commands) pages. ## Pro tips for new users Be specific with your requests Instead of "fix the bug," try "fix the login bug where users see a blank screen after entering wrong credentials." A specific failure mode lets Dropstone go straight to the relevant code instead of exploring the whole project first. Break complex tasks into steps For multi-part work, write the steps out:

1. add a database table for user profiles
2. add an API endpoint to get and update profiles
3. build a page where users can edit their information

Dropstone will execute them in order and verify each before moving on. Let Dropstone explore before changing anything For unfamiliar codebases, ask an exploratory question first ("explain the data flow from /login to the database"). The agent will gather context, which then improves the quality of the edit you ask for next. Match the model tier to the task Stay in Fast for everyday edits. Switch to Pro with /effort high for cross-cutting refactors. Step up to Heavy with /effort xhigh for architecture decisions, large migrations, or hard debugging. Useful keyboard shortcuts
  • / opens the slash command palette
  • Ctrl+P opens the action palette
  • Esc interrupts a running turn cleanly
  • Up arrow recalls a previous prompt
  • Ctrl+T cycles through reasoning effort levels
 ## What's next
CLI reference
Every flag, every subcommand, every option. The page you bookmark.
Slash commands
Every slash command in one place. Comes in handy after a week of use.
Teach Dropstone your repo (AGENTS.md)
Drop a file at the repo root that tells Dropstone your conventions, build commands, and gotchas.
Connect your own tools (MCP)
Wire in databases, internal APIs, ticketing systems, or anything that speaks Model Context Protocol.
Models & providers
More on Fast 1.6, Pro 1.6, and Heavy 1.6, plus how to set a default in your config.
Permissions
Control exactly what Dropstone can read, write, and execute in your projects.
## Getting help - Inside Dropstone, type `/help` or ask in plain language ("how do I switch models?") - Browse the rest of the docs at [docs.dropstone.io](https://docs.dropstone.io) - File an issue or feature request at [dropstone.io/contact](https://dropstone.io/contact) ============================================================================== # Dropstone Pricing - Free, Pro, Max & Enterprise Plans | Compare Features URL: https://docs.dropstone.io/getting-started/pricing Description: Compare Dropstone plans. Free to start, Pro at $20/month, Max 5x at $100 and Max 10x at $200, plus per-seat Teams and custom Enterprise pricing. ============================================================================== Choose the plan that matches how much you code. Upgrade or downgrade at any time with no commitment. For how the weekly pool is metered and what happens when you reach it, see [Usage and limits](./usage). ## Plans Overview ### Usage - Enough usage to try Dropstone daily - Weekly allowance with a visible reset countdown ### Models - Dropstone Fast and Pro - Heavy is not available on Free ### Support - Community support ### Usage - 8× more usage than Free - $200 a year billed annually, a 16.7% discount ### Models - All three production models: Fast, Pro, and Heavy ### Capabilities - Usage credits to keep working past the weekly limit - Larger working context window - Saved agent presets, projects, and workspaces - Access to Blankline Research ### Usage - 5× more usage than Pro - $1,200 a year billed annually ### Everything in Pro, plus - Priority access at high-traffic times - Higher output limits and the highest concurrent task limit - Real phone calls placed on your behalf ### Usage - 10× more usage than Pro - $2,400 a year billed annually ### Everything in Max 5×, plus - Twice the weekly usage of Max 5× - Preview new models before public release - Experimental agent presets and internal-only releases ### Usage - Custom volume and spend limits ### Governance - SSO and SCIM provisioning - Negotiated SLAs ### Support - Dedicated support channel --- ## Feature Comparison ### Plans and usage | | Free | Pro | Max 5× | Max 10× | |---|------|-----|--------|---------| | **Monthly price** | $0 | $20 | $100 | $200 | | **Annual price** | $0 | $200 | $1,200 | $2,400 | | **Weekly usage** | Limited | 8× Free | 5× Pro | 10× Pro | | **Usage credits** | No | Yes | Yes | Yes | | **Output limits per task** | Standard | Standard | Higher | Higher | | **Concurrent tasks** | Standard | Standard | Highest | Highest | | **Priority access at high traffic times** | No | No | Yes | Yes | ### Models All three models run at XHigh thinking on every plan that includes them. | | Free | Pro | Max | |---|------|-----|-----| | **Dropstone Fast** | Yes | Yes | Yes | | **Dropstone Pro** | Yes | Yes | Yes | | **Dropstone Heavy** | No | Yes | Yes | ### Features and capabilities | | Free | Pro | Max | |---|------|-----|-----| | **Generate code** | Yes | Yes | Yes | | **Web search inside the agent** | Yes | Yes | Yes | | **Memory across conversations** | Yes | Yes | Yes | | **Connect any tool through Remote MCP** | Yes | Yes | Yes | | **Context summarization with precision engineering** | No | Yes | Yes | | **Advanced contextual understanding** | No | Yes | Yes | | **Larger working context window** | No | Yes | Yes | | **Saved agent presets and system prompts** | No | Yes | Yes | | **Higher file upload limits** | No | Yes | Yes | ### Surfaces | | Free | Pro | Max | |---|------|-----|-----| | **Dropstone CLI** | Yes | Yes | Yes | | **Dropstone Dashboard** | Yes | Yes | Yes | | **VS Code, Cursor, and Windsurf extension** | Yes | Yes | Yes | | **Remote MCP connectors** | Yes | Yes | Yes | ### Workflow | | Free | Pro | Max | |---|------|-----|-----| | **Code execution in sandbox** | Yes | Yes | Yes | | **Create and edit files in your repo** | Yes | Yes | Yes | | **Plan mode before applying changes** | Yes | Yes | Yes | | **Approval gates on every tool call** | Yes | Yes | Yes | | **Ephemeral / one-off sessions** | Yes | Yes | Yes | | **Saved projects and workspaces** | No | Yes | Yes | ### Research | | Free | Pro | Max | |---|------|-----|-----| | **Access to Blankline Research** | No | Yes | Yes | | **Latest engineering research upgrades** | No | Yes | Yes | | **Access to Beta Research Program** | No | Yes | Yes | | **First look at monthly audit results** | No | Yes | Yes | ### Priority and early access | | Free | Pro | Max | |---|------|-----|-----| | **Dedicated capacity reserved at peak hours** | No | No | Yes | | **Faster first-token latency on every tier** | No | No | Yes | | **Early access to advanced Dropstone features** | No | No | Yes | | **Preview new models before public release** | No | No | Yes | | **Experimental agent presets, internal-only releases** | No | No | Yes | ### Real-World AI | | Free | Pro | Max | |---|------|-----|-----| | **Smart home device control** | No | Yes | Yes | | **Real phone calls placed on your behalf** | No | No | Yes | | **Early access to new Real-World AI capabilities** | No | No | Yes | ### Security and engineering Privacy is enforced the same way on every plan, including Free. It is not a paid upgrade. | | Free | Pro | Max | |---|------|-----|-----| | **Model training on your data** | Strictly no | Strictly no | Strictly no | | **Data retention** | Always zero | Always zero | Always zero | | **Zero prompt, code, or output retention** | Yes | Yes | Yes | | **No data shared with the model's original operator** | Yes | Yes | Yes | | **No routing through labs that train on customer data** | Yes | Yes | Yes | | **Curated tiers, audited monthly by Blankline** | Yes | Yes | Yes | | **Structured evaluation for capability, safety, and provenance** | Yes | Yes | Yes | | **Infrastructure operated and audited by Blankline directly** | Yes | Yes | Yes | ### Billing and payments | | Free | Pro | Max | |---|------|-----|-----| | **Credit card** | n/a | Yes | Yes | | **Billing cycle** | n/a | Monthly | Monthly | | **Cancel anytime** | n/a | Yes | Yes | | **Switch plans midterm** | n/a | Yes | Yes | | **Multi-currency support (USD, INR)** | n/a | Yes | Yes | | **ACH / invoicing / net terms** | Enterprise | Enterprise | Enterprise | --- ## Teams Teams are billed per seat, and you mix two seat types on one account. Standard seats suit most of the team. Premium seats are for the engineers who push the limits. | Seat type | Billed annually | Billed monthly | |-----------|-----------------|----------------| | **Standard** | $25 per seat / month | $30 per seat / month | | **Premium** | $120 per seat / month | $145 per seat / month | Every Teams plan includes a shared workspace with pooled usage, single sign-on, and centralized billing. --- ## Enterprise Enterprise plans cover custom volume and spend limits, SSO and SCIM provisioning, a dedicated support channel, and negotiated SLAs. Pricing is set per contract rather than per seat. --- ## Frequently Asked Questions Can I change plans anytime? Yes. You can upgrade or downgrade at any time, and changes take effect immediately with prorated billing. How is usage metered? Usage is one weekly pool per account, shown as a single percentage with a countdown to the reset. There are no rolling five-hour throttles, and we do not promise a fixed number of turns per week, because the cost of a turn varies by task. What happens if I use up my weekly allowance? By default, requests pause until the pool resets at the start of your next weekly window. The countdown in the usage display tells you exactly when that happens, and moving to a higher plan raises the allowance immediately. If you would rather keep working, turn on **usage credits** and Dropstone draws from your top-up balance instead of stopping. What are usage credits? Usage credits are a prepaid balance that takes over once your weekly plan allowance runs out, so you are not blocked until the window resets. They are **opt-in and off by default** — nothing is charged unless you switch them on, and then only for what you actually consume. Turn them on under Usage credits in [your dashboard](https://www.dropstone.io/dashboard/usage), where you can also top up. Credits are sold at a volume discount of up to 30%, never expire, and are not touched at all while you still have weekly allowance left. Do I need usage credits if I am on Max? Only if you expect to exhaust a Max weekly window, which most people never do. Usage credits are the answer to "I hit the limit and cannot wait", not a required part of any plan. They are available on Pro and Max. What are the model tiers? Dropstone ships three production models. Fast handles quick edits and short turns, Pro is the general-purpose default, and Heavy is for long-horizon reasoning tasks. Heavy is gated to paid plans, because a single long Heavy task can consume an entire free weekly allowance in one request. What is the difference between Max 5× and Max 10×? Both are the same product at different usage multiples. Max 5× gives five times the weekly usage of Pro, and Max 10× gives ten times. Max 10× also carries the highest concurrent task limit on the platform and gets the earliest access to new models and agent presets. How do Enterprise plans work? Enterprise is priced per contract and covers custom volume, SSO and SCIM provisioning, a dedicated support channel, and negotiated SLAs. [Contact our sales team](https://www.dropstone.io/contact) to start. What payment methods do you accept? We accept all major credit cards (Visa, Mastercard, American Express) and support invoicing for Teams and Enterprise plans. --- *For custom requirements or questions about Enterprise access, [contact us](https://www.dropstone.io/contact).* ============================================================================== # Usage and limits URL: https://docs.dropstone.io/getting-started/usage Description: How Dropstone's weekly usage window works, what happens when you reach it, and how usage credits let you keep working past it. ============================================================================== Every Dropstone plan includes a weekly pool of usage shared across all three models. This page explains how that pool works, what happens when it runs out, and how usage credits let you carry on. ## The weekly window Usage is metered as **one weekly pool per account**, shown as a single percentage with a countdown to the reset. - The window is a **rolling 7 days**. It opens on your first chargeable request, not when you sign up, so nothing is spent while you are just looking around. - The reset lands on the same weekday and time for the life of the account. Going quiet for a while does not push it later. - One pool covers Fast, Pro, and Heavy. There is no separate per-model budget to track. - There are no rolling five-hour throttles, and no fixed number of turns per week — the cost of a turn varies with the work it does. Check where you stand at any time: ```bash dropstone ``` The home screen shows your plan and usage, and `/usage` opens the full breakdown with your reset time and cache savings. The same numbers are on [your dashboard](https://www.dropstone.io/dashboard/usage). Heavier models consume the pool faster. A long Heavy task can use in one request what Fast would use across many, which is why Heavy is limited to paid plans. ## When you reach 100% By default, Dropstone stops and tells you when the window is exhausted. You have three ways forward: 1. **Wait for the reset.** The countdown tells you exactly when capacity returns. 2. **Upgrade.** A higher plan raises the allowance immediately — the new capacity is available on your next request, not at the next reset. 3. **Turn on usage credits.** Keep working right now, billed against a prepaid balance. ## Usage credits Usage credits are a prepaid balance that takes over **only after your weekly plan allowance is exhausted**. While you still have plan allowance, credits are never touched. They are **opt-in and off by default**. Nothing is ever charged unless you switch them on, and then only for what you actually consume — an unused balance sits there indefinitely and does not expire. ### Turning them on and off The toggle lives in two places, and both control the same setting — switch it in either and the other follows: - **Dashboard** — [dropstone.io/dashboard/usage](https://www.dropstone.io/dashboard/usage), under **Usage credits**. - **Dropstone Chat** — **Settings → Usage**, under **Usage credits**. Turning it **on** means Dropstone keeps working past your weekly limit, drawing on your balance. Turning it **off** means Dropstone stops at the weekly limit and never touches the balance, which is the default. You can also turn credits on at the moment you need them: when the CLI or chat tells you the weekly limit is reached, the dialog offers to enable them directly if you already have a balance, or to top up if you do not. Either way the change applies to your **very next request** — no restart and no sign-out. That holds in both directions: switching credits off stops any further spending immediately. ### Buying credits Top up from the same page. Credits are sold at a volume discount: | Amount | Discount | |--------|----------| | $5 – $49.99 | — | | $50 – $249.99 | 10% | | $250 – $999.99 | 20% | | $1,000 and above | 30% | The discount applies to typed amounts as well as the presets, so $50 entered by hand gets the same 10% as the $50 button. ### How they are billed Credits are drawn down per request, based on the work each request actually does — there is no per-turn flat fee and no minimum. Requests are billed only while you are over your weekly allowance; the moment your window resets, Dropstone goes back to the plan pool and stops touching the balance. Both the toggle and the remaining balance are read fresh on every request, so changes apply immediately across the CLI, chat, and the dashboard. **Usage credits and API keys share one balance.** If you bought credits for the [HTTP API](/cli/api), turning usage credits on means your CLI and chat sessions can draw from that same balance once your weekly window is spent. Leave the toggle off to keep the balance reserved for API requests. ## Which limit applies to you Dropstone meters three surfaces differently: | Surface | Metered against | Runs out when | |---------|-----------------|---------------| | **CLI and chat** | Your plan's weekly pool | 100% of the weekly window, then usage credits if enabled | | **HTTP API** (API key) | Prepaid credit balance only | Balance reaches $0 — plan allowances never apply | | **Enterprise** | Contracted volume | Per your agreement | ## Related - [Pricing](/getting-started/pricing) — plan allowances and what each tier includes - [HTTP API](/cli/api) — pay-per-use billing for API keys - [Interactive session](/cli/session) — working inside the CLI ============================================================================== # Changelog URL: https://docs.dropstone.io/getting-started/changelog Description: Release notes for Dropstone CLI, including new features, improvements, and bug fixes by version. ============================================================================== Run `dropstone --version` to see your installed version. The native installer keeps you on the latest release automatically; Homebrew and the install script do not auto-update (run `brew upgrade dropstone` or re-run the install script to refresh). --- ### Pre-release notes Versions before 1.0.0 were preview builds and are not documented here. Pre-release binaries are no longer hosted on `download.dropstone.io`. ============================================================================== # Overview URL: https://docs.dropstone.io/cli/overview Description: Dropstone CLI is an agentic coding tool that runs in your terminal. Ask it to read code, run commands, plan changes, and edit files, all from your shell. ============================================================================== Dropstone is the fastest path to agentic coding if you live in the terminal. This page gets you installed, signed in, and into your first conversation. ## Prerequisites - A modern terminal emulator. Any will do; we test against [WezTerm](https://wezterm.org), [Alacritty](https://alacritty.org), [Ghostty](https://ghostty.org), and [Kitty](https://sw.kovidgoyal.net/kitty/). - A Dropstone account. Sign up at [dropstone.io](https://dropstone.io) to use the built-in model lineup (Fast, Pro, Heavy). ## Install Homebrew (recommended): ```bash brew tap blankline-org/dropstone-cli brew install dropstone ``` Or the install script: ```bash curl -fsSL https://dropstone.io/install | bash ``` Both methods drop a single `dropstone` binary on your PATH. No Node, no runtime dependencies. ```bash curl -fsSL https://dropstone.io/install | bash ``` Drops a single `dropstone` binary on your PATH. Works on Debian, Ubuntu, Fedora, RHEL, Alpine, and Arch. PowerShell: ```powershell irm https://dropstone.io/install.ps1 | iex ``` From CMD: ```bash curl -fsSL https://dropstone.io/install.cmd -o install.cmd && install.cmd ``` For a richer terminal experience on Windows, install [WSL](./windows-wsl) and use the Linux one-liner inside it. Verify the install: ```bash dropstone --version ``` ## Sign in Move into any project directory and start Dropstone: ```bash cd /path/to/your/project dropstone ``` On first launch you will be prompted to sign in. Two options: 1. **Continue in browser** (recommended). Opens [dropstone.io/login](https://dropstone.io/login), signs you in, and hands the token back to the CLI automatically. Uses PKCE so the token never appears in your browser URL bar. 2. **Paste a token**. For SSH or headless sessions. Get a token at [dropstone.io/account](https://dropstone.io/account) and paste it in. Run `/login` from inside Dropstone to switch accounts later. ## Pick a model Dropstone ships three model tiers. All three are hosted on US infrastructure and tuned for coding. | Tier | Best for | | ------ | --------------------------------------------------------------------------------- | | Fast | Quick edits, scaffolding, single-file refactors. The default tier. | | Pro | Multi-file refactors, cross-cutting changes, broader reasoning. | | Heavy | Architecture decisions, large migrations, ambiguous or research-heavy debugging. | Switch tiers during a session with `/effort low`, `/effort medium`, `/effort high`, or `/effort xhigh`. `Ctrl+T` cycles through them. See [Models](./models) for more. ## Initialize a project Inside a project root, run: ```text /init ``` Dropstone scans your project structure and creates an `AGENTS.md` file at the repo root. Commit it to git: this is where you encode the project conventions, build commands, and gotchas Dropstone should know on every prompt. See [Rules (AGENTS.md)](./rules) for the full format. ## First conversation You are ready. Ask questions, request changes, or plan features. ### Ask about the code ```text How is authentication handled in @src/auth/session.ts? ``` Use `@` to fuzzy-search for files and pin them into the prompt. ### Plan before building Press Tab to switch into **Plan mode**. In Plan mode, Dropstone cannot edit files; it only describes what it would do. ```text Add a "deleted_at" column to the notes table. Then build a screen that lists recently deleted notes with restore and permanent-delete buttons. ``` Iterate on the plan. When you are happy, press Tab again to return to **Build mode** and tell it to go. ### Direct edits For small changes, skip the plan: ```text Add auth to /settings the same way it is handled in /notes. ``` ### Undo and redo ```text /undo /redo ``` `/undo` reverts the previous edit cycle and re-displays your prompt so you can tweak it. Run it multiple times to walk back further. `/redo` replays an undone step. ## Usage and limits Type `/usage` to see your weekly usage, plan tier, and reset countdown. Type `/upgrade` to open the pricing page if you want more headroom. ============================================================================== # Core concepts URL: https://docs.dropstone.io/cli/concepts Description: Understand the agentic loop, the tools system, sessions, the context window, and the permission model that make Dropstone work. ============================================================================== Dropstone is an agentic coding tool that runs in your terminal. It can read code, run commands, plan changes, edit files, and verify the result. This page covers the core ideas you only need to learn once: the loop the agent runs in, what it can access, how sessions work, how context is managed, and how permissions keep you in control. ## The agentic loop When you give Dropstone a task, it works through three phases: **gather context**, **take action**, and **verify results**. The phases blend together. Dropstone uses tools throughout, whether reading files to understand your code, editing to make changes, or running tests to check its work.
Phase 1
Gather context
Read files, grep for symbols, inspect git state, ask follow-up questions if the task is ambiguous.
Phase 2
Take action
Edit files, write new code, run shell commands. Diffs surface for approval; nothing destructive runs silently.
Phase 3
Verify results
Run type checks, tests, and lints when they exist. If verification fails, loop back to gathering context.
You can press Esc at any point to interrupt and steer.
The loop adapts to what you ask. A question about your codebase might only need context gathering. A bug fix cycles through all three phases. A large refactor might involve heavy verification. Dropstone decides what each step requires based on what it learned from the previous step, chaining dozens of actions together and course-correcting along the way. You are part of this loop too. You can interrupt at any time to redirect, add context, or ask for a different approach. Dropstone works autonomously but stays responsive to your input. The agentic loop is powered by two components: **the model** that reasons, and **tools** that act. ### Models Dropstone uses purpose-built coding models. There are three tiers, each tuned for a different kind of work: | Tier | Best for | | ------ | ---------------------------------------------------------------------------------- | | Fast | Quick edits, scaffolding, single-file refactors, conversational debugging | | Pro | Multi-file refactors, cross-cutting changes, broader reasoning | | Heavy | Architecture decisions, large migrations, ambiguous or research-heavy debugging | Switch tiers with `/effort low`, `/effort medium`, `/effort high`, or `/effort xhigh` during a session, or `Ctrl+T` to cycle through them. When this guide says "Dropstone decides" or "Dropstone chooses," it is the model doing the reasoning. ### Tools Tools are what make Dropstone agentic. Without tools, the model can only produce text. With tools, it can act: read your code, edit files, run commands, search the web, and interact with external services. Each tool result feeds back into the loop, informing the next decision. The built-in tools fall into five categories: | Category | What Dropstone can do | | --------------------- | ----------------------------------------------------------------------------------------------------------- | | **File operations** | Read files, edit code, create new files, rename and reorganize | | **Search** | Find files by glob pattern, search content by regex, explore project structure | | **Execution** | Run shell commands, start servers, run tests, use git | | **Web** | Search the web, fetch documentation, look up error messages | | **Code intelligence** | Read type errors, jump to definitions, find references through LSP | Dropstone chooses which tools to use based on your prompt and what it learns along the way. When you say "fix the failing tests," it might: 1. Run the test suite to see what is failing 2. Read the error output 3. Search for the relevant source files 4. Read those files to understand the code 5. Edit them to fix the issue 6. Run the tests again to verify Each tool use returns information that informs the next step. That is the agentic loop in practice. The built-in tools are the foundation. You can extend what Dropstone knows with [skills](./skills), connect to external services with [MCP servers](./mcp-servers), and offload work to [subagents](./agents). For the complete list of built-in tools, see [Built-in Tools](./tools). ## What Dropstone can access When you run `dropstone` in a directory, the agent gains access to: - **Your project.** Files in your working directory and subdirectories, plus other files with your permission. - **Your terminal.** Any command you could run yourself: build tools, git, package managers, system utilities, scripts. If you can do it from the command line, Dropstone can too. - **Your git state.** Current branch, uncommitted changes, staged files, and recent commit history. - **Your [`AGENTS.md`](./rules).** A markdown file at the repo root where you write project-specific conventions, build commands, gotchas, and anything Dropstone should know every session. - **Extensions you configure.** [MCP servers](./mcp-servers) for external services, [skills](./skills) for workflows, and [subagents](./agents) for delegated work. Because Dropstone sees your whole project, it can work across it. When you ask it to "fix the authentication bug," it searches for relevant files, reads several to understand the context, makes coordinated edits across them, runs tests to verify, and commits if you ask. This is different from inline code assistants that only see the current file. ## Sessions Every interactive session is saved locally. Each message, tool use, and result is written to a session record, which makes it possible to [undo](#undo-with-checkpoints), [resume, and fork](#resume-or-fork-sessions) past work. Sessions are independent. A new session starts with a fresh context window, with no memory of previous conversations. Persistent knowledge belongs in [`AGENTS.md`](./rules), not in conversation history. ### Resume or fork sessions Resuming with `dropstone --continue` (or `dropstone -c`) reopens the most recent session in the current directory and appends new messages to it. Resuming a specific session by id uses `dropstone --session `. ```bash # Continue the last session in this directory dropstone -c # Resume a specific session dropstone --session 7f3a82b1 # Fork an existing session into a new conversation dropstone --session 7f3a82b1 --fork ``` Forking copies the history into a new session id, leaving the original untouched. Useful when you want to explore an alternative direction without losing the original thread. ### The context window The context window holds your conversation history, file contents, command outputs, [`AGENTS.md`](./rules), loaded skills, and system instructions. As you work, the window fills up. Dropstone compacts older content automatically, but instructions from early in the conversation can be lost. A few rules of thumb: - **Put persistent rules in [`AGENTS.md`](./rules)**, not in chat messages. The chat-message version gets compacted out; the `AGENTS.md` version is reloaded every session. - **[Skills](./skills) load on demand.** Dropstone sees skill descriptions at session start but only loads the full content when a skill is invoked. - **[Subagents](./agents) get their own fresh context.** Their work does not bloat the main conversation; when finished, they return a summary. ## Safety: checkpoints and permissions Dropstone has two safety mechanisms. **Checkpoints** let you undo changes the agent has made. **Permissions** control what the agent can do without asking. ### Undo with checkpoints Every file edit is reversible. Before Dropstone edits a file, it snapshots the current contents. If something goes wrong, use `/undo` to walk back one edit cycle at a time, or `/redo` to replay an undone step. ```text /undo # revert the last edit cycle /redo # replay the most recent undone step ``` Checkpoints are local to your session, separate from git. They only cover file changes. Actions that touch remote systems (databases, deployed services, network APIs) cannot be checkpointed, which is why Dropstone asks before running commands with external side effects. ### Control what Dropstone can do Dropstone asks for approval the first time it wants to perform a sensitive action: editing a file, running a shell command, calling out to the network. Approve once, and the same operation runs without re-prompting for the rest of the session. Use [`Tab`](./keybinds) to switch between two operating modes during a session: - **Build mode.** The default. Dropstone can edit files and run commands (subject to approval). Use this when you want to ship the change. - **Plan mode.** Read-only. Dropstone can investigate the codebase, gather context, and produce a plan, but cannot edit or execute anything. Use this when you want to study the system before changing it. To pre-approve commands and skip the prompt entirely, list them in your project's [permissions config](./permissions). For example: ```json { "permissions": { "allow": ["git status", "git diff", "npm test", "npm run lint"] } } ``` For organization-wide policies, finer-grained patterns, and how scope resolution works, see the [Permissions guide](./permissions). ## Working effectively with Dropstone A few patterns that tend to produce better results. ### It is a conversation You do not need a perfect first prompt. Start with what you want, see what the agent does, then correct it: ```text fix the login bug ``` ```text no, the issue is in session handling, not the form validation ``` You are not starting over. You are iterating. Each turn refines the agent's understanding. ### Interrupt and steer You can redirect Dropstone at any point: - **Press `Esc`** to stop immediately. The current tool call is canceled and Dropstone waits for your next instruction. - **Type a correction and press `Enter`** without waiting. Dropstone reads it as soon as the current action completes and adjusts before deciding its next step. ### Be specific up front The more precise your initial prompt, the fewer corrections you will need. Reference files, mention constraints, point to example patterns: ```text the checkout flow is broken for users with expired cards. look in src/payments/ for the issue, especially token refresh. write a failing test first, then fix it. ``` Vague prompts work, but you will spend more time steering. Specific prompts like the one above often succeed on the first attempt. ### Give Dropstone something to verify against The agent performs better when it can check its own work. Include test cases, expected outputs, or acceptance criteria: ```text implement validateEmail. test cases: 'user@example.com' -> true 'invalid' -> false 'user@.com' -> false run the tests after. ``` ### Explore before implementing For complex problems, separate research from coding. Switch to plan mode (Tab), have Dropstone study the relevant code, refine the plan through conversation, then switch back to build mode to execute: ```text read src/auth/ and explain how we handle sessions today. then propose a plan for adding OAuth support. ``` Review the plan, push back on anything you disagree with, then let Dropstone implement. This two-phase approach produces consistently better results than going straight to code. ### Delegate, do not dictate Treat Dropstone like a capable colleague. Give context and direction, then trust the agent to figure out the details: ```text the checkout flow is broken for users with expired cards. the relevant code is in src/payments/. investigate and fix it. ``` You do not need to specify which files to read, which commands to run, or which order to do things in. Dropstone works that out from the prompt. ## What's next
Built-in tools
The full list of tools Dropstone uses and what each one does.
AGENTS.md
Teach Dropstone your project conventions, build commands, and gotchas.
Permissions
Pre-approve commands, scope what Dropstone can run, and write organization policies.
MCP servers
Wire in databases, internal APIs, and any tool that speaks Model Context Protocol.
============================================================================== # CLI URL: https://docs.dropstone.io/cli/cli Description: Dropstone CLI options and commands. ============================================================================== The Dropstone CLI by default starts an [interactive session](/cli/session) when run without any arguments. ```bash dropstone ``` But it also accepts commands as documented on this page. This allows you to interact with Dropstone programmatically. ```bash dropstone run "Explain how closures work in JavaScript" ``` --- ### tui Start an interactive Dropstone session. This is the default when you run `dropstone` with no subcommand; `dropstone tui` is the explicit form. ```bash dropstone [project] ``` #### Flags | Flag | Short | Description | | ------------------------------------------- | ----- | ----------------------------------------------------------------------- | | {"--continue"} | `-c` | Continue the last session | | {"--session"} | `-s` | Session ID to continue | | {"--fork"} | | Fork the session when continuing (use with `--continue` or `--session`) | | {"--prompt"} | | Prompt to use | | {"--model"} | `-m` | Model to use (`dropstone/dropstone-fast`, `dropstone/dropstone-pro`, or `dropstone/dropstone-heavy`) | | {"--agent"} | | Agent to use | | {"--port"} | | Port to listen on | | {"--hostname"} | | Hostname to listen on | | {"--mdns"} | | Enable mDNS discovery | | {"--mdns-domain"} | | Custom mDNS domain name | | {"--cors"} | | Additional browser origin(s) to allow CORS | --- ## Commands The Dropstone CLI also has the following commands. --- ### agent Manage agents for Dropstone. ```bash dropstone agent [command] ``` --- #### create Create a new agent with custom configuration. ```bash dropstone agent create ``` This command will guide you through creating a new agent with a custom system prompt and permission configuration. Anything you don't allow is denied in the generated agent's frontmatter. #### Flags | Flag | Short | Description | | ------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | {"--path"} | | Directory to write the agent file to (defaults to global or `.dropstone/agent` based on the prompt) | | {"--description"} | | What the agent should do | | {"--mode"} | | Agent mode: `all`, `primary`, or `subagent` | | {"--permissions"} | | Comma-separated list of permissions to allow (default: all). Available: `bash`, `read`, `edit`, `glob`, `grep`, `webfetch`, `task`, `todowrite`, `websearch`, `lsp`, `skill`. Anything omitted is denied. Alias: `--tools` | | {"--model"} | `-m` | Model to use (`dropstone/dropstone-fast`, `dropstone/dropstone-pro`, or `dropstone/dropstone-heavy`) | Passing all of `--path`, `--description`, `--mode`, and `--permissions` runs the command non-interactively. --- #### list List all available agents. ```bash dropstone agent list ``` --- ### attach Attach a terminal to an already running Dropstone backend server started via `serve` or `web` commands. ```bash dropstone attach [url] ``` This lets you point an interactive session at a Dropstone server running on another machine. For example: ```bash # On the host machine, start the server dropstone web --port 4096 --hostname 0.0.0.0 # On another machine, attach a session to it dropstone attach http://10.20.30.40:4096 ``` #### Flags | Flag | Short | Description | | ---------------------------------------- | ----- | -------------------------------------------------------------------------- | | {"--dir"} | | Working directory to start the session in | | {"--continue"} | `-c` | Continue the last session | | {"--session"} | `-s` | Session ID to continue | | {"--fork"} | | Fork the session when continuing (use with `--continue` or `--session`) | | {"--password"} | `-p` | Basic auth password (defaults to `DROPSTONE_SERVER_PASSWORD`) | | {"--username"} | `-u` | Basic auth username (defaults to `DROPSTONE_SERVER_USERNAME` or `dropstone`) | --- ### auth Command to manage credentials and login for providers. ```bash dropstone auth [command] ``` --- #### login Use `dropstone auth login` to sign in to Dropstone. Your credentials are stored at `~/.local/share/dropstone/auth.json`. ```bash dropstone auth login ``` Dropstone reads credentials from this file on every launch. ##### Flags | Flag | Short | Description | | ---------------------------------------- | ----- | ---------------------------------------------------- | | {"--provider"} | `-p` | Provider ID or name to log in to | | {"--method"} | `-m` | Login method label to use, skipping method selection | --- #### list Lists all the authenticated providers as stored in the credentials file. ```bash dropstone auth list ``` Or the short version. ```bash dropstone auth ls ``` --- #### logout Logs you out of a provider by clearing it from the credentials file. ```bash dropstone auth logout ``` --- ### github Manage the GitHub agent for repository automation. ```bash dropstone github [command] ``` --- #### install Install the GitHub agent in your repository. ```bash dropstone github install ``` This sets up the necessary GitHub Actions workflow and guides you through the configuration process. [Learn more](./github). --- #### run Run the GitHub agent. This is typically used in GitHub Actions. ```bash dropstone github run ``` ##### Flags | Flag | Description | | ------------------------------------- | -------------------------------------- | | {"--event"} | GitHub mock event to run the agent for | | {"--token"} | GitHub personal access token | --- ### mcp Manage Model Context Protocol servers. ```bash dropstone mcp [command] ``` --- #### add Add an MCP server to your configuration. ```bash dropstone mcp add ``` This command will guide you through adding either a local or remote MCP server. --- #### list List all configured MCP servers and their connection status. ```bash dropstone mcp list ``` Or use the short version. ```bash dropstone mcp ls ``` --- #### auth Authenticate with an OAuth-enabled MCP server. ```bash dropstone mcp auth [name] ``` If you don't provide a server name, you'll be prompted to select from available OAuth-capable servers. You can also list OAuth-capable servers and their authentication status. ```bash dropstone mcp auth list ``` Or use the short version. ```bash dropstone mcp auth ls ``` --- #### logout Remove OAuth credentials for an MCP server. ```bash dropstone mcp logout [name] ``` --- #### debug Debug OAuth connection issues for an MCP server. ```bash dropstone mcp debug ``` --- ### models List the Dropstone model tiers available to your account. ```bash dropstone models ``` Output is in `dropstone/` format. Dropstone ships three tiers: | Model ID | Tier | Best for | | ---------------------------- | ----- | ------------------------------------------------------------------------- | | `dropstone/dropstone-fast` | Fast | Default daily-driver. Quick edits, scaffolding, conversational debugging. | | `dropstone/dropstone-pro` | Pro | Multi-file refactors, cross-cutting changes, broader reasoning. | | `dropstone/dropstone-heavy` | Heavy | Architecture decisions, large migrations, hard debugging. | See [Models](./models) for the full breakdown and how to set a default. #### Flags | Flag | Description | | --------------------------------------- | ------------------------------------------------------------ | | {"--refresh"} | Refresh the cached model list | | {"--verbose"} | Include metadata (context window, capabilities) | --- ### run Run dropstone in non-interactive mode by passing a prompt directly. ```bash dropstone run [message..] ``` This is useful for scripting, automation, or when you want a quick answer without opening an interactive session. For example: ```bash "dropstone run" dropstone run Explain the use of context in Go ``` You can also attach to a running `dropstone serve` instance to avoid MCP server cold boot times on every run: ```bash # Start a headless server in one terminal dropstone serve # In another terminal, run commands that attach to it dropstone run --attach http://localhost:4096 "Explain async/await in JavaScript" ``` #### Flags | Flag | Short | Description | | ------------------------------------------------------------ | ----- | -------------------------------------------------------------------------- | | {"--command"} | | The command to run, use message for args | | {"--continue"} | `-c` | Continue the last session | | {"--session"} | `-s` | Session ID to continue | | {"--fork"} | | Fork the session when continuing (use with `--continue` or `--session`) | | {"--share"} | | Share the session | | {"--model"} | `-m` | Model to use (`dropstone/dropstone-fast`, `dropstone/dropstone-pro`, or `dropstone/dropstone-heavy`) | | {"--agent"} | | Agent to use | | {"--file"} | `-f` | File(s) to attach to message | | {"--format"} | | Format: default (formatted) or json (raw JSON events) | | {"--title"} | | Title for the session (uses truncated prompt if no value provided) | | {"--attach"} | | Attach to a running dropstone server (e.g., http://localhost:4096) | | {"--password"} | `-p` | Basic auth password (defaults to `DROPSTONE_SERVER_PASSWORD`) | | {"--username"} | `-u` | Basic auth username (defaults to `DROPSTONE_SERVER_USERNAME` or `dropstone`) | | {"--dir"} | | Directory to run in, or path on the remote server when attaching | | {"--port"} | | Port for the local server (defaults to random port) | | {"--variant"} | | Model variant (provider-specific reasoning effort) | | {"--thinking"} | | Show thinking blocks | | {"--dangerously-skip-permissions"} | | Auto-approve permissions that are not explicitly denied (dangerous!) | --- ### serve Start a headless Dropstone server for API access. Check out the [server docs](./server) for the full HTTP interface. ```bash dropstone serve ``` This starts a headless HTTP server that provides programmatic access to Dropstone, without opening an interactive session. Set `DROPSTONE_SERVER_PASSWORD` to enable HTTP basic auth (username defaults to `dropstone`). #### Flags | Flag | Description | | ------------------------------------------- | ------------------------------------------ | | {"--port"} | Port to listen on | | {"--hostname"} | Hostname to listen on | | {"--mdns"} | Enable mDNS discovery | | {"--mdns-domain"} | Custom mDNS domain name | | {"--cors"} | Additional browser origin(s) to allow CORS | --- ### session Manage Dropstone sessions. ```bash dropstone session [command] ``` --- #### list List all Dropstone sessions. ```bash dropstone session list ``` ##### Flags | Flag | Short | Description | | ----------------------------------------- | ----- | ------------------------------------ | | {"--max-count"} | `-n` | Limit to N most recent sessions | | {"--format"} | | Output format: table or json (table) | --- #### delete Delete an Dropstone session. ```bash dropstone session delete ``` --- ### stats Show token usage and cost statistics for your Dropstone sessions. ```bash dropstone stats ``` #### Flags | Flag | Description | | --------------------------------------- | --------------------------------------------------------------------------- | | {"--days"} | Show stats for the last N days (all time) | | {"--tools"} | Number of tools to show (all) | | {"--models"} | Show model usage breakdown (hidden by default). Pass a number to show top N | | {"--project"} | Filter by project (all projects, empty string: current project) | --- ### export Export session data as JSON. ```bash dropstone export [sessionID] ``` If you don't provide a session ID, you'll be prompted to select from available sessions. #### Flags | Flag | Description | | ---------------------------------------- | ------------------------------------- | | {"--sanitize"} | Redact sensitive transcript/file data | --- ### import Import session data from a JSON file or Dropstone share URL. ```bash dropstone import ``` You can import from a local file or an Dropstone share URL. ```bash dropstone import session.json dropstone import https://dropstone.io/s/abc123 ``` --- ### web Start a headless Dropstone server with a web interface. ```bash dropstone web ``` This starts an HTTP server and opens a web browser to access Dropstone through a web interface. Set `DROPSTONE_SERVER_PASSWORD` to enable HTTP basic auth (username defaults to `dropstone`). #### Flags | Flag | Description | | ------------------------------------------- | ------------------------------------------ | | {"--port"} | Port to listen on | | {"--hostname"} | Hostname to listen on | | {"--mdns"} | Enable mDNS discovery | | {"--mdns-domain"} | Custom mDNS domain name | | {"--cors"} | Additional browser origin(s) to allow CORS | --- ### acp Start an ACP (Agent Client Protocol) server. ```bash dropstone acp ``` This command starts an ACP server that communicates via stdin/stdout using nd-JSON. #### Flags | Flag | Description | | ------------------------------------------- | ------------------------------------------ | | {"--cwd"} | Working directory | | {"--port"} | Port to listen on | | {"--hostname"} | Hostname to listen on | | {"--mdns"} | Enable mDNS discovery | | {"--mdns-domain"} | Custom mDNS domain name | | {"--cors"} | Additional browser origin(s) to allow CORS | --- ### plugin Install a plugin and update your config. ```bash dropstone plugin ``` Or use the alias. ```bash dropstone plug ``` #### Flags | Flag | Short | Description | | -------------------------------------- | ----- | ------------------------------- | | {"--global"} | `-g` | Install in global config | | {"--force"} | `-f` | Replace existing plugin version | --- ### pr Fetch and checkout a GitHub PR branch, then run Dropstone. ```bash dropstone pr ``` --- ### db Database tools. ```bash dropstone db [query] ``` #### Flags | Flag | Description | | -------------------------------------- | ------------------------------ | | {"--format"} | Output format: `json` or `tsv` | --- #### path Print the database path. ```bash dropstone db path ``` --- ### debug Debugging and troubleshooting tools. ```bash dropstone debug [command] ``` --- ### uninstall Uninstall Dropstone and remove all related files. ```bash dropstone uninstall ``` #### Flags | Flag | Short | Description | | ------------------------------------------- | ----- | ------------------------------------------- | | {"--keep-config"} | `-c` | Keep configuration files | | {"--keep-data"} | `-d` | Keep session data and snapshots | | {"--dry-run"} | | Show what would be removed without removing | | {"--force"} | `-f` | Skip confirmation prompts | --- ### upgrade Updates Dropstone CLI to the latest version or a specific version. `dropstone update` is an alias and behaves identically. ```bash dropstone upgrade [target] # or dropstone update [target] ``` To upgrade to the latest version: ```bash dropstone upgrade ``` To install a specific version: ```bash dropstone upgrade 1.0.5 ``` On Windows, if Dropstone is currently running, the installer stages the new build as `dropstone.exe.pending`. The new version activates automatically on the next launch: no manual file moves required. #### Flags | Flag | Short | Description | | -------------------------------------- | ----- | ------------------------------------------------------------------------------------ | | {"--method"} | `-m` | The installation method to use: `curl`, `npm`, `pnpm`, `bun`, `brew`, `scoop`, `choco` | --- ## Global Flags The dropstone CLI takes the following global flags. | Flag | Short | Description | | ------------------------------------------ | ----- | ------------------------------------ | | {"--help"} | `-h` | Display help | | {"--version"} | `-v` | Print version number | | {"--print-logs"} | | Print logs to stderr | | {"--log-level"} | | Log level (DEBUG, INFO, WARN, ERROR) | | {"--pure"} | | Run without external plugins | --- ## Environment variables Dropstone reads the following environment variables on launch. These are the supported user-facing variables; anything not listed here is internal and may change or be removed without notice. | Variable | Type | Description | | ------------------------------ | ------- | -------------------------------------------------------------------- | | `DROPSTONE_API_KEY` | string | Dropstone API key for headless / CI use (skips browser sign-in) | | `DROPSTONE_CONFIG` | string | Path to a `dropstone.json` config file | | `DROPSTONE_TUI_CONFIG` | string | Path to a session config file (`tui.json`) | | `DROPSTONE_DISABLE_AUTOUPDATE` | boolean | Disable automatic CLI update checks | | `DROPSTONE_GIT_BASH_PATH` | string | Path to Git Bash on Windows (used as the shell tool) | | `DROPSTONE_SERVER_PASSWORD` | string | Enable HTTP basic auth on `dropstone serve` / `dropstone web` | | `DROPSTONE_SERVER_USERNAME` | string | Override the basic auth username (default `dropstone`) | ============================================================================== # Interactive session URL: https://docs.dropstone.io/cli/session Description: How to work inside a Dropstone session. File references, shell escapes, slash commands, and editor integration. ============================================================================== Dropstone runs as an interactive session in your terminal. Each session is tied to the directory you launched it from, holds the conversation history, and stays open until you exit. This page covers how to drive a session: how to reference files, run shell commands, use slash commands, and connect an external editor. ## Start a session Run `dropstone` from inside a project: ```bash dropstone ``` Or point it at a specific directory: ```bash dropstone /path/to/project ``` Once Dropstone is up, type any natural-language prompt: ```text Give me a quick summary of the codebase. ``` ## Change the workspace Started in the wrong place? You do not have to quit and `cd`. Press ctrl+o on the home screen — the same shortcut as **Open Folder** in VS Code — or click **Open folder** under the path in the welcome panel. The Open folder picker, listing the current directory and its parent The picker opens on your current directory: - **Open this folder** uses the directory you are standing in. - Choosing any listed subfolder moves into it, so you can walk down a tree. - **..** goes up a level. - Type to filter the list, or paste an absolute path — or one starting with `~` — to jump straight there. Selecting the .. entry to move up to the parent directory Hidden directories are left out, so `.git` and `.config` do not bury what you are looking for. You can still reach one by pasting its path. Choosing a folder **restarts Dropstone** there. A session's working directory is fixed when it starts — the agent, the file index and the session history are all keyed to it — so changing folders means a fresh start rather than a live swap. The current conversation ends and Dropstone reopens on the home screen in the new folder. The shortcut is the `workspace.open` command and can be [rebound](./keybinds). It is also in the command palette (ctrl+p) as **Open folder**, which is the way in if your terminal intercepts ctrl+o. ## File references Reference files in your messages with `@`. This does a fuzzy search across the current working directory. ```text How is auth handled in @src/api/index.ts? ``` The file's contents are added to the conversation automatically, so the agent can read it without grepping for it first. ## Shell commands Start a message with `!` to run a shell command. The output is added to the conversation as a tool result so the agent can react to it. ```bash !ls -la ``` ```bash !git diff ``` ## Slash commands Type `/` followed by a command name to perform a quick action. Most have a keyboard shortcut using `ctrl+x` as the leader key (configurable via [Keybindings](./keybinds)). ```bash /help ``` ### compact Compact the current session. Older context is summarized so newer work has room. *Alias:* `/summarize`. **Keybind:** `ctrl+x c` ### details Toggle whether tool execution details are shown inline. ### editor Open your external editor to compose a longer message. Uses the editor set in `EDITOR`. See [Editor setup](#editor-setup). **Keybind:** `ctrl+x e` ### effort Adjust the active model's reasoning depth. Opens a picker with four levels: **low**, **medium**, **high**, **xhigh**. Higher effort yields deeper reasoning at the cost of more credits and slightly higher latency. *Alias:* `/thinking`. ### exit Exit Dropstone. *Aliases:* `/quit`, `/q`. **Keybind:** `ctrl+x q` ### export Export the current conversation to Markdown and open it in your editor (uses `EDITOR`). **Keybind:** `ctrl+x x` ### help Show the help dialog with every slash command and keybind. ### init Guided setup for creating or updating `AGENTS.md`. See [Rules (AGENTS.md)](./rules). ### models List the available models for this session. **Keybind:** `ctrl+x m` ### new Start a new session in the current directory. *Alias:* `/clear`. **Keybind:** `ctrl+x n` ### redo Redo a previously undone message. Only available after `/undo`. File changes are restored as part of the redo. Undo and redo use Git to manage file-state snapshots, so your project must be a Git repository. **Keybind:** `ctrl+x r` ### sessions List and switch between sessions. *Aliases:* `/resume`, `/continue`. **Keybind:** `ctrl+x l` ### undo Undo the last message in the conversation. Removes the most recent user message, all subsequent responses, and any file changes made in those turns. Undo uses Git to revert file changes, so your project must be a Git repository. **Keybind:** `ctrl+x u` ### upgrade Open the Dropstone pricing page to upgrade your plan. Use this when you need more weekly credits or access to premium tiers (Dropstone Pro, Dropstone Heavy). `/upgrade` is the **plan** upgrade. To update the Dropstone CLI binary itself, run `dropstone update` from your shell. ### usage Show the current week's credit consumption, plan name, weekly limit, and when credits next reset. ## Editor setup The `/editor` and `/export` commands launch the editor in your `EDITOR` environment variable. ```bash # Terminal editors export EDITOR=nano export EDITOR=vim # GUI editors (VS Code, Cursor, VSCodium, Windsurf, Zed, etc.) # require --wait so the editor process blocks until closed export EDITOR="code --wait" ``` To make this permanent, add it to your shell profile (`~/.bashrc`, `~/.zshrc`, and so on). ```bash set EDITOR=notepad # GUI editors need --wait set EDITOR=code --wait ``` To make this permanent, set it via **System Properties** → **Environment Variables**. ```powershell $env:EDITOR = "notepad" # GUI editors need --wait $env:EDITOR = "code --wait" ``` To make this permanent, add the line to your PowerShell profile. Popular options: - `code` for Visual Studio Code - `cursor` for Cursor - `windsurf` for Windsurf - `nvim` for Neovim - `vim` for Vim - `nano` for Nano - `subl` for Sublime Text - `notepad` for Windows Notepad GUI editors like VS Code return immediately by default, which would skip your message. The `--wait` flag makes the editor process block until you close the file, so Dropstone can read what you wrote. ## Customisation A handful of session-level preferences live in the command palette (`Ctrl+P`). Search for what you want to change; the setting is remembered across sessions. - **Hide username**: drops your username from chat messages - **Diff style**: choose between adaptive (default) and single-column stacked diffs - **Mouse capture**: toggle whether the terminal handles mouse selection itself, or Dropstone does For everything else (keybinds, formatters, config file format), see the dedicated pages: [Keybindings](./keybinds), [Formatters](./formatters), [Configuration](./config). ## Privacy and data retention Your prompts, code, and conversation transcripts are never used to train models and are not retained beyond the lifetime of your session. Dropstone uses session-scoped prompt caching to reduce cost and latency, the same way Anthropic and OpenAI do: cached content is isolated to your own account, expires automatically, and is never reused for any other user or sent to model training. These controls are enforced and reviewed by Blankline, Dropstone's parent company. Blankline's compliance team audits Dropstone's data handling on a recurring basis and retains revocation authority over the production access of any individual or system that breaches the policy. See the [Trust page](https://dropstone.io/trust) for the full posture, including subprocessor disclosures and the runtime security boundary. ============================================================================== # Commands URL: https://docs.dropstone.io/cli/commands Description: Create custom commands for repetitive tasks. ============================================================================== Custom commands let you specify a prompt you want to run when that command is executed in your session. ```bash frame="none" /my-command ``` Custom commands are in addition to the built-in commands like `/init`, `/undo`, `/redo`, `/help`. [Learn more](/cli/session#slash-commands). --- ## Create command files Create markdown files in the `commands/` directory to define custom commands. Create `.dropstone/commands/test.md`: ```md title=".dropstone/commands/test.md" --- description: Run tests with coverage agent: build model: dropstone/dropstone-pro --- Run the full test suite with coverage report and show any failures. Focus on the failing tests and suggest fixes. ``` The frontmatter defines command properties. The content becomes the template. Use the command by typing `/` followed by the command name. ```bash frame="none" /test ``` --- ## Configure You can add custom commands through the Dropstone config or by creating markdown files in the `commands/` directory. --- ### JSON Use the `command` option in your Dropstone [config](./config): ```json title="dropstone.jsonc" {4-12} { "$schema": "https://dropstone.io/schema/config.json", "command": { // This becomes the name of the command "test": { // This is the prompt that will be sent to the LLM "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.", // Shown as the description in the slash command palette "description": "Run tests with coverage", "agent": "build", "model": "dropstone/dropstone-pro" } } } ``` Now you can run this command from any session: ```bash frame="none" /test ``` --- ### Markdown You can also define commands using markdown files. Place them in: - Global: `~/.config/dropstone/commands/` - Per-project: `.dropstone/commands/` ```markdown title="~/.config/dropstone/commands/test.md" --- description: Run tests with coverage agent: build model: dropstone/dropstone-pro --- Run the full test suite with coverage report and show any failures. Focus on the failing tests and suggest fixes. ``` The markdown file name becomes the command name. For example, `test.md` lets you run: ```bash frame="none" /test ``` --- ## Prompt config The prompts for the custom commands support several special placeholders and syntax. --- ### Arguments Pass arguments to commands using the `$ARGUMENTS` placeholder. ```md title=".dropstone/commands/component.md" --- description: Create a new component --- Create a new React component named $ARGUMENTS with TypeScript support. Include proper typing and basic structure. ``` Run the command with arguments: ```bash frame="none" /component Button ``` And `$ARGUMENTS` will be replaced with `Button`. You can also access individual arguments using positional parameters: - `$1` - First argument - `$2` - Second argument - `$3` - Third argument - And so on... For example: ```md title=".dropstone/commands/create-file.md" --- description: Create a new file with content --- Create a file named $1 in the directory $2 with the following content: $3 ``` Run the command: ```bash frame="none" /create-file config.json src "{ \"key\": \"value\" }" ``` This replaces: - `$1` with `config.json` - `$2` with `src` - `$3` with `{ "key": "value" }` --- ### Shell output Use _!`command`_ to inject [shell command](/cli/session#shell-commands) output into your prompt. For example, to create a custom command that analyzes test coverage: ```md title=".dropstone/commands/analyze-coverage.md" --- description: Analyze test coverage --- Here are the current test results: !`npm test` Based on these results, suggest improvements to increase coverage. ``` Or to review recent changes: ```md title=".dropstone/commands/review-changes.md" --- description: Review recent changes --- Recent git commits: !`git log --oneline -10` Review these changes and suggest any improvements. ``` Commands run in your project's root directory and their output becomes part of the prompt. --- ### File references Include files in your command using `@` followed by the filename. ```md title=".dropstone/commands/review-component.md" --- description: Review component --- Review the component in @src/components/Button.tsx. Check for performance issues and suggest improvements. ``` The file content gets included in the prompt automatically. --- ## Options Let's look at the configuration options in detail. --- ### Template The `template` option defines the prompt that will be sent to the LLM when the command is executed. ```json title="dropstone.json" { "command": { "test": { "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes." } } } ``` This is a **required** config option. --- ### Description Use the `description` option to provide a brief description of what the command does. ```json title="dropstone.json" { "command": { "test": { "description": "Run tests with coverage" } } } ``` This is shown next to the command in the slash command palette. --- ### Agent Use the `agent` config to optionally specify which [agent](./agents) should execute this command. If this is a [subagent](./agents#subagents) the command will trigger a subagent invocation by default. To disable this behavior, set `subtask` to `false`. ```json title="dropstone.json" { "command": { "review": { "agent": "plan" } } } ``` This is an **optional** config option. If not specified, defaults to your current agent. --- ### Subtask Use the `subtask` boolean to force the command to trigger a [subagent](./agents#subagents) invocation. This is useful if you want the command to not pollute your primary context and will **force** the agent to act as a subagent, even if `mode` is set to `primary` on the [agent](./agents) configuration. ```json title="dropstone.json" { "command": { "analyze": { "subtask": true } } } ``` This is an **optional** config option. --- ### Model Use the `model` config to override the default model for this command. ```json title="dropstone.json" { "command": { "analyze": { "model": "dropstone/dropstone-pro" } } } ``` This is an **optional** config option. --- ## Built-in Dropstone includes several built-in commands like `/init`, `/undo`, `/redo`, `/help`. [Learn more](/cli/session#slash-commands). Custom commands can override built-ins. If you define a custom command with the same name as a built-in, the custom one wins. ============================================================================== # Keybinds URL: https://docs.dropstone.io/cli/keybinds Description: Customize your keyboard shortcuts. ============================================================================== Customize Dropstone's keyboard shortcuts with `keymap` in `tui.json`. `keymap` is merged with the built-in defaults, so you only need to configure the shortcuts you want to change. The older `keybinds` field is still accepted as a migration fallback but is deprecated. If `keymap` is present, Dropstone ignores `keybinds`. --- ## Leader key Dropstone uses a `leader` key for many shortcuts. This avoids conflicts in your terminal. By default, `ctrl+x` is the leader key and leader shortcuts require you to first press the leader key and then the shortcut. For example, to start a new session you first press `ctrl+x` and then press `n`. You do not need to use a leader key, but we recommend doing so. --- ## Minimal example ```json title="tui.json" { "$schema": "https://dropstone.io/schema/tui.json", "keymap": { "leader": "ctrl+x", "leader_timeout": 2000, "sections": { "global": { "command.palette.show": "ctrl+p", "session.new": "n", "session.list": "l" }, "session": { "session.compact": "c", "session.undo": "u", "session.redo": "r" }, "input": { "input.submit": "return", "input.newline": ["shift+return", "ctrl+return", "alt+return", "ctrl+j"] } } } } ``` --- ## Keymap structure `keymap.sections` is grouped by semantic area. Each section contains command names and the key sequence that triggers them. | Field | Description | | ---------------- | --------------------------------------------------------------------------------------------------- | | `leader` | The key used by `` sequences. Defaults to `ctrl+x`. | | `leader_timeout` | How long Dropstone waits for the next key after the leader key, in milliseconds. Defaults to `2000`. | | `sections` | A map of UI areas to command bindings. | --- ## Binding values A string can contain one shortcut or multiple comma-separated shortcuts. You can also use an array for multiple shortcuts, or `"none"`/`false` to disable a command. ```json title="tui.json" { "$schema": "https://dropstone.io/schema/tui.json", "keymap": { "sections": { "session": { "session.compact": "none", "session.export": "x,ctrl+shift+x", "session.copy": ["y", "ctrl+shift+c"] } } } } ``` For advanced cases, use an object with `key`, `event`, `preventDefault`, or `fallthrough`. ```json title="tui.json" { "$schema": "https://dropstone.io/schema/tui.json", "keymap": { "sections": { "prompt": { "prompt.paste": { "key": "ctrl+v", "preventDefault": false } } } } } ``` --- ## Keymap reference These are the user-facing commands you can bind. Commands set to `"none"` are available to bind but disabled by default. ```json title="tui.json" { "$schema": "https://dropstone.io/schema/tui.json", "keymap": { "leader": "ctrl+x", "leader_timeout": 2000, "sections": { "global": { "command.palette.show": "ctrl+p", "session.list": "l", "session.new": "n", "model.list": "m", "model.cycle_recent": "f2", "model.cycle_recent_reverse": "shift+f2", "agent.list": "a", "agent.cycle": "tab", "agent.cycle.reverse": "shift+tab", "variant.cycle": "ctrl+t", "variant.list": "none", "help.show": "none", "workspace.open": "ctrl+o,o", "app.exit": "ctrl+c,ctrl+d,q", "terminal.suspend": "ctrl+z" }, "session": { "session.rename": "ctrl+r", "session.timeline": "g", "session.fork": "none", "session.compact": "c", "session.undo": "u", "session.redo": "r", "session.sidebar.toggle": "b", "session.toggle.conceal": "h", "session.page.up": "pageup,ctrl+alt+b", "session.page.down": "pagedown,ctrl+alt+f", "session.line.up": "ctrl+alt+y", "session.line.down": "ctrl+alt+e", "session.half.page.up": "ctrl+alt+u", "session.half.page.down": "ctrl+alt+d", "session.first": "ctrl+g,home", "session.last": "ctrl+alt+g,end", "messages.copy": "y", "session.copy": "none", "session.export": "x", "session.child.first": "down", "session.parent": "up", "session.child.next": "right", "session.child.previous": "left" }, "prompt": { "prompt.submit": "none", "prompt.editor": "e", "session.interrupt": "escape", "prompt.clear": "ctrl+c", "prompt.paste": { "key": "ctrl+v", "preventDefault": false }, "prompt.history.previous": "up", "prompt.history.next": "down" }, "autocomplete": { "prompt.autocomplete.prev": "up,ctrl+p", "prompt.autocomplete.next": "down,ctrl+n", "prompt.autocomplete.hide": "escape", "prompt.autocomplete.select": "return", "prompt.autocomplete.complete": "tab" }, "input": { "input.submit": "return", "input.newline": "shift+return,ctrl+return,alt+return,ctrl+j", "input.move.left": "left,ctrl+b", "input.move.right": "right,ctrl+f", "input.move.up": "up", "input.move.down": "down", "input.select.left": "shift+left", "input.select.right": "shift+right", "input.select.up": "shift+up", "input.select.down": "shift+down", "input.line.home": "ctrl+a", "input.line.end": "ctrl+e", "input.select.line.home": "ctrl+shift+a", "input.select.line.end": "ctrl+shift+e", "input.visual.line.home": "alt+a", "input.visual.line.end": "alt+e", "input.select.visual.line.home": "alt+shift+a", "input.select.visual.line.end": "alt+shift+e", "input.buffer.home": "home", "input.buffer.end": "end", "input.select.buffer.home": "shift+home", "input.select.buffer.end": "shift+end", "input.delete.line": "ctrl+shift+d", "input.delete.to.line.end": "ctrl+k", "input.delete.to.line.start": "ctrl+u", "input.backspace": "backspace,shift+backspace", "input.delete": "ctrl+d,delete,shift+delete", "input.undo": "ctrl+-,super+z", "input.redo": "ctrl+.,super+shift+z", "input.word.forward": "alt+f,alt+right,ctrl+right", "input.word.backward": "alt+b,alt+left,ctrl+left", "input.select.word.forward": "alt+shift+f,alt+shift+right", "input.select.word.backward": "alt+shift+b,alt+shift+left", "input.delete.word.forward": "alt+d,alt+delete,ctrl+delete", "input.delete.word.backward": "ctrl+w,ctrl+backspace,alt+backspace", "input.select.all": "super+a" }, "dialog_select": { "dialog.select.prev": "up,ctrl+p", "dialog.select.next": "down,ctrl+n", "dialog.select.page_up": "pageup", "dialog.select.page_down": "pagedown", "dialog.select.home": "home", "dialog.select.end": "end", "dialog.select.submit": "return" }, "dialog_actions": { "dialog.action.toggle": "space", "dialog.action.delete": "ctrl+d", "dialog.action.rename": "ctrl+r" }, "permission": { "permission.reject.cancel": "ctrl+c,ctrl+d,q", "permission.prompt.escape": "ctrl+c,ctrl+d,q", "permission.prompt.fullscreen": "ctrl+f" }, "question": { "question.reject": "ctrl+c,ctrl+d,q", "question.edit.clear": "ctrl+c" }, "home_tips": { "tips.toggle": "h" } } } } ``` --- ## Legacy keybinds `keybinds` is deprecated. It is kept so existing configs continue to work while users migrate to `keymap`. Only use `keybinds` when `keymap` is not present. If both fields are set, `keymap` wins and `keybinds` are ignored for shortcut resolution. ```json title="tui.json" { "$schema": "https://dropstone.io/schema/tui.json", "keybinds": { "command_list": "ctrl+p", "session_new": "n", "session_compact": "c" } } ``` On native Windows, the defaults for undo and terminal suspend are different for both `keymap` and legacy `keybinds`: - `input.undo` defaults to `ctrl+z,ctrl+-,super+z` when not explicitly configured (the `ctrl+z` binding is added because Windows terminals do not support POSIX suspend). - `terminal.suspend` is disabled because native Windows terminals do not support POSIX suspend. --- ## Built-in input shortcuts The prompt input supports common Readline/Emacs-style shortcuts for editing text. These are built-in defaults: you can override them in the `input` section of `tui.json` above. | Shortcut | Action | | -------- | ---------------------------------------- | | `ctrl+a` | Move to start of current line | | `ctrl+e` | Move to end of current line | | `ctrl+b` | Move cursor back one character | | `ctrl+f` | Move cursor forward one character | | `alt+b` | Move cursor back one word | | `alt+f` | Move cursor forward one word | | `ctrl+d` | Delete character under cursor | | `ctrl+k` | Kill to end of line | | `ctrl+u` | Kill to start of line | | `ctrl+w` | Kill previous word | | `alt+d` | Kill next word | | `ctrl+t` | Transpose characters | | `ctrl+g` | Cancel popovers / abort running response | --- ## Shift+Enter Some terminals don't send modifier keys with Enter by default. You may need to configure your terminal to send `Shift+Enter` as an escape sequence. ### Windows Terminal Open your `settings.json` at: ``` %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json ``` Add this to the root-level `actions` array: ```json "actions": [ { "command": { "action": "sendInput", "input": "\u001b[13;2u" }, "id": "User.sendInput.ShiftEnterCustom" } ] ``` Add this to the root-level `keybindings` array: ```json "keybindings": [ { "keys": "shift+enter", "id": "User.sendInput.ShiftEnterCustom" } ] ``` Save the file and restart Windows Terminal or open a new tab. ============================================================================== # Config URL: https://docs.dropstone.io/cli/config Description: Using the Dropstone JSON config. ============================================================================== You can configure Dropstone using a JSON config file. --- ## Format Dropstone supports both **JSON** and **JSONC** (JSON with Comments) formats. ```json title="dropstone.jsonc" { "$schema": "https://dropstone.io/schema/config.json", "model": "dropstone/dropstone-pro", "autoupdate": true, "server": { "port": 4096, }, } ``` --- ## Locations You can place your config in a couple of different locations and they have a different order of precedence. Configuration files are **merged together**, not replaced. Settings from the following config locations are combined. Later configs override earlier ones only for conflicting keys. Non-conflicting settings from all configs are preserved. For example, if your global config sets `autoupdate: true` and your project config sets `model: "dropstone/dropstone-pro"`, the final configuration will include both settings. --- ### Precedence order Config sources are loaded in this order (later sources override earlier ones): 1. **Remote config** (from `.well-known/dropstone`) - organizational defaults 2. **Global config** (`~/.config/dropstone/dropstone.json`) - user preferences 3. **Custom config** (`DROPSTONE_CONFIG` env var) - custom overrides 4. **Project config** (`dropstone.json` in project) - project-specific settings 5. **`.dropstone` directories** - agents, commands, plugins 6. **Managed config files** (`/Library/Application Support/dropstone/` on macOS) - admin-controlled 7. **macOS managed preferences** (`.mobileconfig` via MDM) - highest priority, not user-overridable This means project configs can override global defaults, and global configs can override remote organizational defaults. Managed settings override everything. The `.dropstone` and `~/.config/dropstone` directories use **plural names** for subdirectories: `agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`. Singular names (e.g. `agent/`) are also supported for backwards compatibility. --- ### Remote Organizations can provide default configuration via a `.well-known/dropstone` endpoint on their domain. Dropstone fetches this automatically on first sign-in for users whose account is enrolled with that organization. Remote config is loaded first, serving as the base layer. All other config sources (global, project) can override these defaults. For example, if your organization provides MCP servers that are disabled by default: ```json title="Remote config from .well-known/dropstone" { "mcp": { "jira": { "type": "remote", "url": "https://jira.example.com/mcp", "enabled": false } } } ``` You can enable specific servers in your local config: ```json title="dropstone.json" { "mcp": { "jira": { "type": "remote", "url": "https://jira.example.com/mcp", "enabled": true } } } ``` --- ### Global Place your global Dropstone config in `~/.config/dropstone/dropstone.json`. Use global config for user-wide preferences like models and permissions. For session-level settings (keybinds, scroll, mouse capture), use `~/.config/dropstone/tui.json`. Global config overrides remote organizational defaults. --- ### Per project Add `dropstone.json` in your project root. Project config has the highest precedence among standard config files - it overrides both global and remote configs. For project-specific session settings, add `tui.json` alongside it. Place project-specific config in the root of your project. When Dropstone starts up, it looks for a config file in the current directory or traverse up to the nearest Git directory. This is also safe to be checked into Git and uses the same schema as the global one. --- ### Custom path Specify a custom config file path using the `DROPSTONE_CONFIG` environment variable. ```bash export DROPSTONE_CONFIG=/path/to/my/custom-config.json dropstone run "Hello world" ``` Custom config is loaded between global and project configs in the precedence order. --- ### Managed settings Organizations can enforce configuration that users cannot override. Managed settings are loaded at the highest priority tier. #### File-based Drop an `dropstone.json` or `dropstone.jsonc` file in the system managed config directory: | Platform | Path | | -------- | ---------------------------------------- | | macOS | `/Library/Application Support/dropstone/` | | Linux | `/etc/dropstone/` | | Windows | `%ProgramData%\dropstone` | These directories require admin/root access to write, so users cannot modify them. #### macOS managed preferences On macOS, Dropstone reads managed preferences from the `ai.dropstone.managed` preference domain. Deploy a `.mobileconfig` via MDM (Jamf, Kandji, FleetDM) and the settings are enforced automatically. Dropstone checks these paths: 1. `/Library/Managed Preferences//ai.dropstone.managed.plist` 2. `/Library/Managed Preferences/ai.dropstone.managed.plist` The plist keys map directly to `dropstone.json` fields. MDM metadata keys (`PayloadUUID`, `PayloadType`, etc.) are stripped automatically. **Creating a `.mobileconfig`** Use the `ai.dropstone.managed` PayloadType. The Dropstone config keys go directly in the payload dict: ```xml PayloadContent PayloadType ai.dropstone.managed PayloadIdentifier com.example.dropstone.config PayloadUUID GENERATE-YOUR-OWN-UUID PayloadVersion 1 share disabled server hostname 127.0.0.1 permission * ask bash * ask rm -rf * deny PayloadType Configuration PayloadIdentifier com.example.dropstone PayloadUUID GENERATE-YOUR-OWN-UUID PayloadVersion 1 ``` Generate unique UUIDs with `uuidgen`. Customize the settings to match your organization's requirements. **Deploying via MDM** - **Jamf Pro:** Computers > Configuration Profiles > Upload > scope to target devices or smart groups - **FleetDM:** Add the `.mobileconfig` to your gitops repo under `mdm.macos_settings.custom_settings` and run `fleetctl apply` **Verifying on a device** Double-click the `.mobileconfig` to install locally for testing (shows in System Settings > Privacy & Security > Profiles), then run: ```bash dropstone debug config ``` All managed preference keys appear in the resolved config and cannot be overridden by user or project configuration. --- ## Schema The main config schema is defined in [**`dropstone.io/config.json`**](https://dropstone.io/schema/config.json). Session-level config (`tui.json`) uses [**`dropstone.io/tui.json`**](https://dropstone.io/schema/tui.json). Your editor should be able to validate and autocomplete based on the schema. --- ### Session config Use a dedicated `tui.json` (or `tui.jsonc`) file for session-level settings: scroll behaviour, mouse capture, diff rendering, and so on. ```json title="tui.json" { "$schema": "https://dropstone.io/schema/tui.json", "scroll_speed": 3, "scroll_acceleration": { "enabled": true }, "diff_style": "auto", "mouse": true } ``` Legacy `theme`, `keybinds`, and session-related keys in `dropstone.json` are deprecated and automatically migrated when possible. --- ### Server You can configure server settings for the `dropstone serve` and `dropstone web` commands through the `server` option. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "server": { "port": 4096, "hostname": "0.0.0.0", "mdns": true, "mdnsDomain": "myproject.local", "cors": ["http://localhost:5173"] } } ``` Available options: - `port` - Port to listen on. - `hostname` - Hostname to listen on. When `mdns` is enabled and no hostname is set, defaults to `0.0.0.0`. - `mdns` - Enable mDNS service discovery. This allows other devices on the network to discover your Dropstone server. - `mdnsDomain` - Custom domain name for mDNS service. Defaults to `dropstone.local`. Useful for running multiple instances on the same network. - `cors` - Additional origins to allow for CORS when using the HTTP server from a browser-based client. Values must be full origins (scheme + host + optional port), eg `https://app.example.com`. [Learn more about the server here](./server). --- ### Shell You can configure the shell used for the interactive terminal using the `shell` option. Compatible shells are also used for agent tool calls. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "shell": "pwsh" } ``` If not specified, Dropstone will automatically discover and use a sensible default based on your operating system (e.g. `pwsh` or `cmd.exe` on Windows, `/bin/zsh` or `/bin/bash` on macOS/Linux). You can provide an absolute path or a short name. --- ### Tools You can manage the tools an LLM can use through the `tools` option. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "tools": { "write": false, "bash": false } } ``` [Learn more about tools here](./tools). --- ### Model Set your default model with the `model` option. Dropstone ships three tiers: | Tier | Model ID | | ----- | ---------------------------- | | Fast | `dropstone/dropstone-fast` | | Pro | `dropstone/dropstone-pro` | | Heavy | `dropstone/dropstone-heavy` | ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "model": "dropstone/dropstone-pro" } ``` Pin a default reasoning depth with `variant`: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "model": "dropstone/dropstone-pro", "variant": "high" } ``` Valid `variant` values are `low`, `medium`, `high`, `xhigh`. See [Models](./models) for the full breakdown. The `small_model` option configures a separate model for lightweight tasks like title generation. By default Dropstone picks an appropriate tier; you can override it explicitly: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "model": "dropstone/dropstone-pro", "small_model": "dropstone/dropstone-fast" } ``` --- ### Agents You can configure specialized agents for specific tasks through the `agent` option. ```json title="dropstone.jsonc" { "$schema": "https://dropstone.io/schema/config.json", "agent": { "code-reviewer": { "description": "Reviews code for best practices and potential issues", "model": "dropstone/dropstone-pro", "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.", "tools": { // Disable file modification tools for review-only agent "write": false, "edit": false, }, }, }, } ``` You can also define agents using markdown files in `~/.config/dropstone/agents/` or `.dropstone/agents/`. [Learn more here](./agents). --- ### Default agent You can set the default agent using the `default_agent` option. This determines which agent is used when none is explicitly specified. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "default_agent": "plan" } ``` The default agent must be a primary agent (not a subagent). This can be a built-in agent like `"build"` or `"plan"`, or a [custom agent](./agents) you've defined. If the specified agent doesn't exist or is a subagent, Dropstone will fall back to `"build"` with a warning. This setting applies across all interfaces: interactive sessions, one-shot runs (`dropstone run`), and the GitHub Action. --- ### Commands You can configure custom commands for repetitive tasks through the `command` option. ```json title="dropstone.jsonc" { "$schema": "https://dropstone.io/schema/config.json", "command": { "test": { "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.", "description": "Run tests with coverage", "agent": "build", "model": "dropstone/dropstone-fast", }, "component": { "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.", "description": "Create a new component", }, }, } ``` You can also define commands using markdown files in `~/.config/dropstone/commands/` or `.dropstone/commands/`. [Learn more here](./commands). --- ### Keymap Customize keyboard shortcuts in `tui.json` with `keymap`. ```json title="tui.json" { "$schema": "https://dropstone.io/schema/tui.json", "keymap": { "sections": { "global": { "command.palette.show": "ctrl+p" } } } } ``` `keymap` is merged with built-in defaults, so you only need to configure the shortcuts you want to change. The older `keybinds` field is deprecated and only applies when `keymap` is not present. [Learn more here](./keybinds). --- ### Snapshot Dropstone uses snapshots to track file changes during agent operations, enabling you to undo and revert changes within a session. Snapshots are enabled by default. For large repositories or projects with many submodules, the snapshot system can cause slow indexing and significant disk usage. You can disable snapshots using the `snapshot` option. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "snapshot": false } ``` Note that disabling snapshots means changes made by the agent cannot be rolled back through the UI. --- ### Autoupdate Dropstone will automatically download any new updates when it starts up. You can disable this with the `autoupdate` option. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "autoupdate": false } ``` If you don't want updates but want to be notified when a new version is available, set `autoupdate` to `"notify"`. Notice that this only works if it was not installed using a package manager such as Homebrew. --- ### Formatters You can enable and configure code formatters through the `formatter` option. Omit it to keep formatters disabled. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "formatter": true } ``` Use an object to keep built-ins enabled while configuring overrides or custom formatters. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "formatter": { "prettier": { "disabled": true }, "custom-prettier": { "command": ["npx", "prettier", "--write", "$FILE"], "environment": { "NODE_ENV": "development" }, "extensions": [".js", ".ts", ".jsx", ".tsx"] } } } ``` [Learn more about formatters here](./formatters). --- ### LSP Servers You can enable and configure LSP servers through the `lsp` option. Omit it to keep LSP disabled. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "lsp": true } ``` Use an object to keep built-ins enabled while configuring overrides or custom LSP servers. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "lsp": { "typescript": { "disabled": true } } } ``` [Learn more about LSP servers here](./lsp). --- ### Permissions By default, dropstone **allows all operations** without requiring explicit approval. You can change this using the `permission` option. For example, to ensure that the `edit` and `bash` tools require user approval: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "permission": { "edit": "ask", "bash": "ask" } } ``` [Learn more about permissions here](./permissions). --- ### Compaction You can control context compaction behavior through the `compaction` option. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "compaction": { "auto": true, "prune": true, "reserved": 10000 } } ``` - `auto` - Automatically compact the session when context is full (default: `true`). - `prune` - Remove old tool outputs to save tokens (default: `true`). - `reserved` - Token buffer for compaction. Leaves enough window to avoid overflow during compaction --- ### Watcher You can configure file watcher ignore patterns through the `watcher` option. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "watcher": { "ignore": ["node_modules/**", "dist/**", ".git/**"] } } ``` Patterns follow glob syntax. Use this to exclude noisy directories from file watching. --- ### MCP servers You can configure MCP servers you want to use through the `mcp` option. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "mcp": {} } ``` [Learn more here](./mcp-servers). --- ### Plugins [Plugins](./plugins) extend Dropstone with custom tools, hooks, and integrations. Place plugin files in `.dropstone/plugins/` or `~/.config/dropstone/plugins/`. You can also load plugins from npm through the `plugin` option. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "plugin": ["@my-org/custom-plugin", "./local-plugin.ts"] } ``` [Learn more here](./plugins). --- ### Instructions You can configure the instructions for the model you're using through the `instructions` option. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"] } ``` This takes an array of paths and glob patterns to instruction files. [Learn more about rules here](./rules). --- ### Experimental The `experimental` key contains options that are under active development. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "experimental": {} } ``` Experimental options are not stable. They may change or be removed without notice. --- ## Variables You can use variable substitution in your config files to reference environment variables and file contents. --- ### Env vars Use `{env:VARIABLE_NAME}` to substitute environment variables: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "model": "{env:DROPSTONE_MODEL}" } ``` If the environment variable is not set, it will be replaced with an empty string. --- ### Files Use `{file:path/to/file}` to substitute the contents of a file: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "instructions": ["./custom-instructions.md"] } ``` File paths can be: - Relative to the config file directory - Or absolute paths starting with `/` or `~` These are useful for: - Including large instruction files without cluttering your config. - Sharing common configuration snippets across multiple config files. ============================================================================== # Models URL: https://docs.dropstone.io/cli/models Description: Choosing between Dropstone Fast 1.7, Pro 1.7, and Heavy 1.7, the three model tiers Dropstone ships, plus how to set defaults and tune reasoning depth. ============================================================================== Dropstone ships three model tiers that cover the full range of coding work, from cheap throwaway questions to long-horizon agentic refactors. You pick a tier; Dropstone runs the inference. There is no concept of an external "provider" to configure. ## The three tiers | Tier | Model ID | Best for | | ----------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- | | **Fast 1.7** | `dropstone/dropstone-fast` | Default daily-driver. Chat, single-file edits, quick answers, code review, simple tool use. Cheapest, fastest. | | **Pro 1.7** | `dropstone/dropstone-pro` | Frontier coding capability with a balanced speed/cost tradeoff. Multi-file edits, bugs that need real reasoning, design discussions. | | **Heavy 1.7** | `dropstone/dropstone-heavy` | Long-horizon work: architecture, large refactors, multi-agent orchestration. Deepest reasoning ceiling. | To switch between them during a session: ```bash /models ``` or press `Ctrl+X M`. ## How to set a default Add the model ID to your `dropstone.json`. Project config overrides global config, so you can pick a different default per-project. ### Set Fast 1.7 as your default ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "model": "dropstone/dropstone-fast" } ``` ### Set Pro 1.7 as your default ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "model": "dropstone/dropstone-pro" } ``` ### Set Heavy 1.7 as your default ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "model": "dropstone/dropstone-heavy" } ``` You can also pick a model for a single run with `--model`: ```bash dropstone --model dropstone/dropstone-heavy ``` ## Reasoning depth Each tier supports four reasoning depths via `/effort`: - `low`: fast answers, minimal credits - `medium`: everyday balance (default) - `high`: deeper reasoning for tricky problems - `xhigh`: maximum reasoning depth, biggest credit spend Switch during a session: ```bash /effort ``` To lock in a depth as your default, add `variant`: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "model": "dropstone/dropstone-pro", "variant": "high" } ``` Trivial questions on `low` cost a fraction of `high`-effort answers. Pick the level that matches the task. ## The 1.7 version naming Fast, Pro, and Heavy are **branded names**, not specific model checkpoints. Each carries a calendar-aligned version suffix: - `1.7` means **Year 1, Month 7** - `1.8` will mean **Year 1, Month 8** - And so on Every month, the best frontier coding model for each tier is re-evaluated and the top performer becomes the new month's pick. The brand stays stable; the underlying model improves over time. This is documented openly on the [Dropstone Trust page](https://dropstone.io/trust): each release's branded tier and its underlying model are public. You always know what's powering your prompts. ## Legacy (previous-generation) models Each month a new lineup ships (for example **1.7**), and the previous month's tiers (for example **1.6**) stay available for anyone who needs to pin to or roll back to them. To keep the picker focused on the current lineup, these older tiers are marked experimental and are **hidden by default**. To reveal them, set the `DROPSTONE_ENABLE_EXPERIMENTAL_MODELS` environment variable to `true` (or `1`) before launching Dropstone. There is no slash command or config-file key for this; it is read from the environment of the CLI process. ```powershell title="Windows PowerShell" $env:DROPSTONE_ENABLE_EXPERIMENTAL_MODELS = "true" dropstone ``` ```bash title="macOS / Linux (bash / zsh)" DROPSTONE_ENABLE_EXPERIMENTAL_MODELS=true dropstone # or persist it in your shell profile (~/.zshrc, ~/.bashrc): export DROPSTONE_ENABLE_EXPERIMENTAL_MODELS=true ``` With the flag set, the previous-generation tiers appear in `/models` and in `dropstone models`, and become selectable exactly like the current ones: | Tier | Model ID | | --------- | ------------------------------- | | Fast 1.6 | `dropstone/dropstone-fast-1.6` | | Pro 1.6 | `dropstone/dropstone-pro-1.6` | | Heavy 1.6 | `dropstone/dropstone-heavy-1.6` | You can pin one as your default like any other model (the `--model` flag works for a single run too): ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "model": "dropstone/dropstone-pro-1.6" } ``` Only the immediately previous lineup is kept available; older generations are retired. Unsetting the variable (or setting it to anything other than `true` / `1`) hides the legacy tiers again. Retired models that are not in the current or previous lineup cannot be re-enabled this way. ## Switching tiers mid-session Use the command palette or a keyboard shortcut to switch without restarting. The conversation history persists across tier changes. | Action | Slash command | Shortcut | | ------------------------------------- | ------------- | ---------- | | Switch tier (Fast / Pro / Heavy) | `/models` | `Ctrl+X M` | | Quick-switch to a recently-used tier | | `F2` | | Adjust reasoning depth | `/effort` | | ## Picking the right tier | Workload | Tier | Why | | ----------------------------------------- | ------------ | ------------------------------------------------------------------ | | "What does this function do?" | Fast | Single-file context, fast answer needed | | "Fix this bug in `auth.ts`" | Fast or Pro | Pro if the bug needs deeper reasoning | | "Refactor the entire `routes/` directory" | Pro or Heavy | Multi-file changes benefit from longer-context reasoning | | "Design a new caching layer for our API" | Heavy | Architecture-level reasoning needs the deepest model | | Daily quick-fix flow | Fast | 5× more turns per dollar than the top frontier CLIs | When in doubt: start on Fast and step up if the answer isn't deep enough. ## Loading order When Dropstone starts, it picks a model in this priority: 1. The `--model` / `-m` command-line flag (e.g. `dropstone --model dropstone/dropstone-pro`) 2. The `model` value in your `dropstone.json` config 3. The last-used model from the previous session 4. Fast 1.7 as the safe default ============================================================================== # Agents URL: https://docs.dropstone.io/cli/agents Description: Configure and use specialized agents. ============================================================================== Agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access. Use the plan agent to analyze code and review suggestions without making any code changes. You can switch between agents during a session or invoke them with the `@` mention. --- ## Types There are two types of agents in Dropstone; primary agents and subagents. --- ### Primary agents Primary agents are the main assistants you interact with directly. You can cycle through them using the **Tab** key, or your configured `switch_agent` keybind. These agents handle your main conversation. Tool access is configured via permissions: for example, Build has all tools enabled while Plan is restricted. You can use the **Tab** key to switch between primary agents during a session. Dropstone comes with two built-in primary agents, **Build** and **Plan**. We'll look at these below. --- ### Subagents Subagents are specialized assistants that primary agents can invoke for specific tasks. You can also manually invoke them by **@ mentioning** them in your messages. Dropstone comes with two built-in subagents, **General** and **Explore**. We'll look at this below. --- ## Built-in Dropstone comes with two built-in primary agents and two built-in subagents. --- ### Use build _Mode_: `primary` Build is the **default** primary agent with all tools enabled. This is the standard agent for development work where you need full access to file operations and system commands. --- ### Use plan _Mode_: `primary` A restricted agent designed for planning and analysis. We use a permission system to give you more control and prevent unintended changes. By default, all of the following are set to `ask`: - `file edits`: All writes, patches, and edits - `bash`: All bash commands This agent is useful when you want the LLM to analyze code, suggest changes, or create plans without making any actual modifications to your codebase. --- ### Use general _Mode_: `subagent` A general-purpose agent for researching complex questions and executing multi-step tasks. Has full tool access (except todo), so it can make file changes when needed. Use this to run multiple units of work in parallel. --- ### Use explore _Mode_: `subagent` A fast, read-only agent for exploring codebases. Cannot modify files. Use this when you need to quickly find files by patterns, search code for keywords, or answer questions about the codebase. --- ### Use compaction _Mode_: `primary` Hidden system agent that compacts long context into a smaller summary. It runs automatically when needed and is not selectable in the UI. --- ### Use title _Mode_: `primary` Hidden system agent that generates short session titles. It runs automatically and is not selectable in the UI. --- ### Use summary _Mode_: `primary` Hidden system agent that creates session summaries. It runs automatically and is not selectable in the UI. --- ## Usage 1. For primary agents, use the **Tab** key to cycle through them during a session. You can also use your configured `switch_agent` keybind. 2. Subagents can be invoked: - **Automatically** by primary agents for specialized tasks based on their descriptions. - Manually by **@ mentioning** a subagent in your message. For example. ```txt frame="none" @general help me search for this function ``` 3. **Navigation between sessions**: When subagents create child sessions, use `session_child_first` (default: **\+Down**) to enter the first child session from the parent. 4. Once you are in a child session, use: - `session_child_cycle` (default: **Right**) to cycle to the next child session - `session_child_cycle_reverse` (default: **Left**) to cycle to the previous child session - `session_parent` (default: **Up**) to return to the parent session This lets you switch between the main conversation and specialized subagent work. --- ## Configure You can customize the built-in agents or create your own through configuration. Agents can be configured in two ways: --- ### JSON Configure agents in your `dropstone.json` config file: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "agent": { "build": { "mode": "primary", "model": "dropstone/dropstone-pro", "prompt": "{file:./prompts/build.txt}", "permission": { "edit": "allow", "bash": "allow" } }, "plan": { "mode": "primary", "model": "dropstone/dropstone-fast", "permission": { "edit": "deny", "bash": "deny" } }, "code-reviewer": { "description": "Reviews code for best practices and potential issues", "mode": "subagent", "model": "dropstone/dropstone-pro", "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.", "permission": { "edit": "deny" } } } } ``` --- ### Markdown You can also define agents using markdown files. Place them in: - Global: `~/.config/dropstone/agents/` - Per-project: `.dropstone/agents/` ```markdown title="~/.config/dropstone/agents/review.md" --- description: Reviews code for quality and best practices mode: subagent model: dropstone/dropstone-pro temperature: 0.1 permission: edit: deny bash: deny --- You are in code review mode. Focus on: - Code quality and best practices - Potential bugs and edge cases - Performance implications - Security considerations Provide constructive feedback without making direct changes. ``` The markdown file name becomes the agent name. For example, `review.md` creates a `review` agent. --- ## Options Let's look at these configuration options in detail. --- ### Description Use the `description` option to provide a brief description of what the agent does and when to use it. ```json title="dropstone.json" { "agent": { "review": { "description": "Reviews code for best practices and potential issues" } } } ``` This is a **required** config option. --- ### Temperature Control the randomness and creativity of the LLM's responses with the `temperature` config. Lower values make responses more focused and deterministic, while higher values increase creativity and variability. ```json title="dropstone.json" { "agent": { "plan": { "temperature": 0.1 }, "creative": { "temperature": 0.8 } } } ``` Temperature values typically range from 0.0 to 1.0: - **0.0-0.2**: Very focused and deterministic responses, ideal for code analysis and planning - **0.3-0.5**: Balanced responses with some creativity, good for general development tasks - **0.6-1.0**: More creative and varied responses, useful for brainstorming and exploration ```json title="dropstone.json" { "agent": { "analyze": { "temperature": 0.1, "prompt": "{file:./prompts/analysis.txt}" }, "build": { "temperature": 0.3 }, "brainstorm": { "temperature": 0.7, "prompt": "{file:./prompts/creative.txt}" } } } ``` If no temperature is specified, Dropstone uses a sensible default tuned for each tier. --- ### Max steps Control the maximum number of agentic iterations an agent can perform before being forced to respond with text only. This allows users who wish to control costs to set a limit on agentic actions. If this is not set, the agent will continue to iterate until the model chooses to stop or the user interrupts the session. ```json title="dropstone.json" { "agent": { "quick-thinker": { "description": "Fast reasoning with limited iterations", "prompt": "You are a quick thinker. Solve problems with minimal steps.", "steps": 5 } } } ``` When the limit is reached, the agent receives a special system prompt instructing it to respond with a summarization of its work and recommended remaining tasks. The legacy `maxSteps` field is deprecated. Use `steps` instead. --- ### Disable Set to `true` to disable the agent. ```json title="dropstone.json" { "agent": { "review": { "disable": true } } } ``` --- ### Prompt Specify a custom system prompt file for this agent with the `prompt` config. The prompt file should contain instructions specific to the agent's purpose. ```json title="dropstone.json" { "agent": { "review": { "prompt": "{file:./prompts/code-review.txt}" } } } ``` This path is relative to where the config file is located. So this works for both the global Dropstone config and the project specific config. --- ### Model Use the `model` config to override the model for this agent. Useful for using different models optimized for different tasks. For example, a faster model for planning, a more capable model for implementation. If you don't specify a model, primary agents use the [globally configured model](./config#model) while subagents inherit the model of the primary agent that invoked them. ```json title="dropstone.json" { "agent": { "plan": { "model": "dropstone/dropstone-fast" } } } ``` The model ID uses the format `dropstone/`. Use `dropstone/dropstone-fast`, `dropstone/dropstone-pro`, or `dropstone/dropstone-heavy`. --- ### Tools (deprecated) `tools` is **deprecated**. Prefer the agent's [`permission`](#permissions) field for new configs, updates and more fine-grained control. Allows you to control which tools are available in this agent. You can enable or disable specific tools by setting them to `true` or `false`. In an agent's `tools` config, `true` is equivalent to `{"*": "allow"}` permission and `false` is equivalent to `{"*": "deny"}` permission. ```json title="dropstone.json" {3-6,9-12} { "$schema": "https://dropstone.io/schema/config.json", "tools": { "write": true, "bash": true }, "agent": { "plan": { "tools": { "write": false, "bash": false } } } } ``` The agent-specific config overrides the global config. You can also use wildcards in legacy `tools` entries to control multiple tools at once. For example, to disable all tools from an MCP server: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "agent": { "readonly": { "tools": { "mymcp_*": false, "write": false, "edit": false } } } } ``` [Learn more about tools](./tools). --- ### Permissions You can configure permissions to manage what actions an agent can take. Each permission key can be set to: - `"ask"`: Prompt for approval before running the tool - `"allow"`: Allow all operations without approval - `"deny"`: Disable the tool The available permission keys are: | Key | Tools it gates | | -------------------- | ---------------------------------------------------------------- | | `read` | `read` | | `edit` | `write`, `edit`, `apply_patch` | | `glob` | `glob` | | `grep` | `grep` | | `list` | `list` | | `bash` | `bash` | | `task` | `task` | | `external_directory` | Any tool that reads or writes files outside the project worktree | | `todowrite` | `todowrite`, `todoread` | | `webfetch` | `webfetch` | | `websearch` | `websearch` | | `lsp` | `lsp` | | `skill` | `skill` | | `question` | `question` | | `doom_loop` | Recovery prompts when an agent appears stuck | `read`, `edit`, `glob`, `grep`, `list`, `bash`, `task`, `external_directory`, `lsp`, and `skill` accept either a shorthand action (`"allow" | "ask" | "deny"`) or an object of glob/pattern → action for fine-grained control. The remaining keys accept the shorthand action only. Permission keys are matched as wildcard patterns against the underlying tool name, so the same syntax works for built-ins, custom tools, and MCP tools. For example `"mymcp_*": "deny"` denies every tool from an MCP server, and `"mymcp_search": "ask"` targets a single one. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "permission": { "edit": "deny" } } ``` You can override these permissions per agent. ```json title="dropstone.json" {3-5,8-10} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "edit": "deny" }, "agent": { "build": { "permission": { "edit": "ask" } } } } ``` You can also set permissions in Markdown agents. ```markdown title="~/.config/dropstone/agents/review.md" --- description: Code review without edits mode: subagent permission: edit: deny bash: "*": ask "git diff": allow "git log*": allow "grep *": allow webfetch: deny --- Only analyze code and suggest changes. ``` You can set permissions for specific bash commands. ```json title="dropstone.json" {7} { "$schema": "https://dropstone.io/schema/config.json", "agent": { "build": { "permission": { "bash": { "git push": "ask", "grep *": "allow" } } } } } ``` This can take a glob pattern. ```json title="dropstone.json" {7} { "$schema": "https://dropstone.io/schema/config.json", "agent": { "build": { "permission": { "bash": { "git *": "ask" } } } } } ``` And you can also use the `*` wildcard to manage permissions for all commands. Since the last matching rule takes precedence, put the `*` wildcard first and specific rules after. ```json title="dropstone.json" {8} { "$schema": "https://dropstone.io/schema/config.json", "agent": { "build": { "permission": { "bash": { "*": "ask", "git status *": "allow" } } } } } ``` [Learn more about permissions](./permissions). --- ### Mode Control the agent's mode with the `mode` config. The `mode` option is used to determine how the agent can be used. ```json title="dropstone.json" { "agent": { "review": { "mode": "subagent" } } } ``` The `mode` option can be set to `primary`, `subagent`, or `all`. If no `mode` is specified, it defaults to `all`. --- ### Hidden Hide a subagent from the `@` autocomplete menu with `hidden: true`. Useful for internal subagents that should only be invoked programmatically by other agents via the Task tool. ```json title="dropstone.json" { "agent": { "internal-helper": { "mode": "subagent", "hidden": true } } } ``` This only affects user visibility in the autocomplete menu. Hidden agents can still be invoked by the model via the Task tool if permissions allow. Only applies to `mode: subagent` agents. --- ### Task permissions Control which subagents an agent can invoke via the Task tool with `permission.task`. Uses glob patterns for flexible matching. ```json title="dropstone.json" { "agent": { "orchestrator": { "mode": "primary", "permission": { "task": { "*": "deny", "orchestrator-*": "allow", "code-reviewer": "ask" } } } } } ``` When set to `deny`, the subagent is removed from the Task tool description entirely, so the model won't attempt to invoke it. Rules are evaluated in order, and the **last matching rule wins**. In the example above, `orchestrator-planner` matches both `*` (deny) and `orchestrator-*` (allow), but since `orchestrator-*` comes after `*`, the result is `allow`. Users can always invoke any subagent directly via the `@` autocomplete menu, even if the agent's task permissions would deny it. --- ### Color Customize the agent's visual appearance in the UI with the `color` option. This affects how the agent appears in the interface. Use a valid hex color (e.g., `#FF5733`) or theme color: `primary`, `secondary`, `accent`, `success`, `warning`, `error`, `info`. ```json title="dropstone.json" { "agent": { "creative": { "color": "#ff6b6b" }, "code-reviewer": { "color": "accent" } } } ``` --- ### Top P Control response diversity with the `top_p` option. Alternative to temperature for controlling randomness. ```json title="dropstone.json" { "agent": { "brainstorm": { "top_p": 0.9 } } } ``` Values range from 0.0 to 1.0. Lower values are more focused, higher values more diverse. --- ### Additional Any other options you specify in your agent configuration are **passed through directly** as model options. For Dropstone's tiers, the supported pass-through options are reasoning depth and text verbosity: ```json title="dropstone.json" {6,7} { "agent": { "deep-thinker": { "description": "Agent that uses high reasoning effort for complex problems", "model": "dropstone/dropstone-heavy", "variant": "xhigh", "textVerbosity": "low" } } } ``` Run `dropstone models` to see the available tiers. --- ## Create agents You can create new agents using the following command: ```bash dropstone agent create ``` This interactive command will: 1. Ask where to save the agent; global or project-specific. 2. Description of what the agent should do. 3. Generate an appropriate system prompt and identifier. 4. Let you select which permissions the agent should be allowed (anything you don't select is denied). 5. Finally, create a markdown file with the agent configuration. --- ## Use cases Here are some common use cases for different agents. - **Build agent**: Full development work with all tools enabled - **Plan agent**: Analysis and planning without making changes - **Review agent**: Code review with read-only access plus documentation tools - **Debug agent**: Focused on investigation with bash and read tools enabled - **Docs agent**: Documentation writing with file operations but no system commands --- ## Examples Here are some example agents you might find useful. Have an agent you'd like to share? [Get in touch](https://dropstone.io/contact) and we'll feature it. --- ### Documentation agent ```markdown title="~/.config/dropstone/agents/docs-writer.md" --- description: Writes and maintains project documentation mode: subagent permission: bash: deny --- You are a technical writer. Create clear, comprehensive documentation. Focus on: - Clear explanations - Proper structure - Code examples - User-friendly language ``` --- ### Security auditor ```markdown title="~/.config/dropstone/agents/security-auditor.md" --- description: Performs security audits and identifies vulnerabilities mode: subagent permission: edit: deny --- You are a security expert. Focus on identifying potential security issues. Look for: - Input validation vulnerabilities - Authentication and authorization flaws - Data exposure risks - Dependency vulnerabilities - Configuration security issues ``` ============================================================================== # Rules URL: https://docs.dropstone.io/cli/rules Description: Set custom instructions for dropstone. ============================================================================== You can provide custom instructions to dropstone by creating an `AGENTS.md` file. This is similar to Cursor's rules. It contains instructions that will be included in the LLM's context to customize its behavior for your specific project. --- ## Initialize To create a new `AGENTS.md` file, you can run the `/init` command in dropstone. Commit your project's `AGENTS.md` file to Git so the rest of your team picks up the same rules. `/init` scans the important files in your repo, may ask a couple of targeted questions when the codebase cannot answer them, and then creates or updates `AGENTS.md` with concise project-specific guidance. It focuses on the things future agent sessions are most likely to need: - build, lint, and test commands - command order and focused verification steps when they matter - architecture and repo structure that are not obvious from filenames alone - project-specific conventions, setup quirks, and operational gotchas - references to existing instruction sources like Cursor or Copilot rules If you already have an `AGENTS.md`, `/init` will improve it in place instead of blindly replacing it. --- ## Example You can also just create this file manually. Here's an example of some things you can put into an `AGENTS.md` file. ```markdown title="AGENTS.md" # SST v3 Monorepo Project This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management. ## Project Structure - `packages/` - Contains all workspace packages (functions, core, web, etc.) - `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts) - `sst.config.ts` - Main SST configuration with dynamic imports ## Code Standards - Use TypeScript with strict mode enabled - Shared code goes in `packages/core/` with proper exports configuration - Functions go in `packages/functions/` - Infrastructure should be split into logical files in `infra/` ## Monorepo Conventions - Import shared modules using workspace names: `@my-app/core/example` ``` We are adding project-specific instructions here and this will be shared across your team. --- ## Types dropstone also supports reading the `AGENTS.md` file from multiple locations. And this serves different purposes. ### Project Place an `AGENTS.md` in your project root for project-specific rules. These only apply when you are working in this directory or its sub-directories. ### Global You can also have global rules in a `~/.config/dropstone/AGENTS.md` file. This gets applied across all dropstone sessions. Since this isn't committed to Git or shared with your team, we recommend using this to specify any personal rules that the LLM should follow. ### Claude Code Compatibility For users migrating from Claude Code, Dropstone reads Claude Code's file conventions as fallbacks: - **Project rules**: `CLAUDE.md` in your project directory (used if no `AGENTS.md` exists) - **Global rules**: `~/.claude/CLAUDE.md` (used if no `~/.config/dropstone/AGENTS.md` exists) - **Skills**: `~/.claude/skills/` (see [Skills](./skills) for details) To stop Dropstone from reading the Claude Code locations, remove or rename those files (or commit the equivalent content into `AGENTS.md` so the project takes precedence). --- ## Precedence When Dropstone starts, it looks for rule files in this order: 1. **Local files** by traversing up from the current directory (`AGENTS.md`, `CLAUDE.md`) 2. **Global file** at `~/.config/dropstone/AGENTS.md` 3. **Claude Code file** at `~/.claude/CLAUDE.md` (if neither of the above is present) The first matching file wins in each category. For example, if you have both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is used. Similarly, `~/.config/dropstone/AGENTS.md` takes precedence over `~/.claude/CLAUDE.md`. --- ## Custom Instructions You can specify custom instruction files in your `dropstone.json` or the global `~/.config/dropstone/dropstone.json`. This allows you and your team to reuse existing rules rather than having to duplicate them to AGENTS.md. Example: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"] } ``` You can also use remote URLs to load instructions from the web. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"] } ``` Remote instructions are fetched with a 5 second timeout. All instruction files are combined with your `AGENTS.md` files. --- ## Referencing External Files While dropstone doesn't automatically parse file references in `AGENTS.md`, you can achieve similar functionality in two ways: ### Using dropstone.json The recommended approach is to use the `instructions` field in `dropstone.json`: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"] } ``` ### Manual Instructions in AGENTS.md You can teach dropstone to read external files by providing explicit instructions in your `AGENTS.md`. Here's a practical example: ```markdown title="AGENTS.md" # TypeScript Project Rules ## External File Loading CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand. Instructions: - Do NOT preemptively load all references - use lazy loading based on actual need - When loaded, treat content as mandatory instructions that override defaults - Follow references recursively when needed ## Development Guidelines For TypeScript code style and best practices: @docs/typescript-guidelines.md For React component architecture and hooks patterns: @docs/react-patterns.md For REST API design and error handling: @docs/api-standards.md For testing strategies and coverage requirements: @test/testing-guidelines.md ## General Guidelines Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md. ``` This approach allows you to: - Create modular, reusable rule files - Share rules across projects via symlinks or git submodules - Keep AGENTS.md concise while referencing detailed guidelines - Ensure dropstone loads files only when needed for the specific task For monorepos or projects with shared standards, using `dropstone.json` with glob patterns (like `packages/*/AGENTS.md`) is more maintainable than manual instructions. ============================================================================== # Memory - What Dropstone Remembers and How to Change It URL: https://docs.dropstone.io/cli/memory Description: Dropstone remembers standing rules and facts across sessions. Learn how it decides what to keep, how to see everything it has learned, and how to make it forget. ============================================================================== Dropstone remembers things between sessions. Correct it once and it should not need correcting again, in this project or the next one. This page explains what it keeps, how that reaches your next conversation, and how to change or remove any of it. Memory requires being signed in to Dropstone. If you are not signed in, the memory tools are not loaded and nothing is stored. --- ## Two kinds of memory Not everything worth remembering should be treated the same way, so Dropstone keeps two kinds. ### Standing rules A rule is something you want followed **from now on**. A convention, a style preference, a prohibition. > "Always use arrow function consts, never `function` declarations." > > "Never add a dependency without asking." > > "Use bun, not npm." Rules are applied to **every task**, without being searched for. That is the point: a rule about how you like functions written has to apply when you ask for a slug helper, a date parser, or anything else. Waiting until the task "looks related" would mean the rule silently stops applying the moment the subject changes. ### Facts A fact is something that is simply true right now. > "The staging database is behind the VPN." > > "This project pins Node 22." Facts are recalled **only when they are relevant** to what you are working on. There are far more of them, and pulling all of them into every conversation would be noise. --- ## How something gets remembered You do not have to say "remember this." Dropstone records a lesson when you **correct it, reject an approach, or state a preference** — the moment it happens, not at the end of the task. ``` You: No. I never want `function` declarations, always arrow consts. Dropstone: Noted - arrow function consts over declarations. ``` It also decides which kind it is. Something phrased as a standing instruction ("always", "never", "use X not Y") becomes a rule. Everything else is stored as a fact. When it is unsure it chooses fact, because a missed rule costs you one reminder while a wrong rule follows you everywhere. Nothing is stored unless you are signed in, and memory is private to your account. --- ## Seeing what it remembers Just ask. ``` You: what do you remember about me? ``` Dropstone lists what it has learned, with rules shown separately from facts, because rules are the ones affecting every reply. You can also ask for one kind: ``` You: show me my standing rules ``` --- ## Changing or removing something Tell it to forget, and it will. ``` You: forget the rule about arrow functions Dropstone: Forgotten. It will not be applied again. ``` Dropstone only forgets when **you** ask. It will not remove something on its own initiative, and it will not claim something was removed if it was not — if it cannot find the entry, it says so rather than pretending. You can also correct a rule instead of deleting it. Restating a preference updates it in place, so you do not end up with two rules contradicting each other. --- ## Memory and AGENTS.md These solve different problems and work well together. | | `AGENTS.md` | Memory | |---|---|---| | Written by | you | Dropstone, from your corrections | | Lives in | your repository | your account | | Shared with | anyone who clones the repo | just you | | Best for | project conventions the whole team needs | how *you* like to work | If a rule belongs to the project, put it in [AGENTS.md](/cli/rules) so your teammates get it too. If it is a personal preference that should follow you between projects, let memory handle it. --- ## Turning it off Memory writing follows your **Improve Dropstone** setting. Turn it off in account settings and nothing is recorded. You can also disable memory recall for a single machine: ```bash DROPSTONE_DISABLE_MEMORY_GATE=1 ``` Recall failing never blocks a session — if memory is unavailable, Dropstone carries on without it. --- ## Good practice **Be direct when correcting.** "Always X, never Y" is unmistakably a rule. "I think maybe X is nicer" may be stored as a fact and only resurface when relevant. **Check your rules occasionally.** They apply to everything, so a stale one is worth removing. Asking "show me my standing rules" takes a second. **Keep project conventions in `AGENTS.md`.** Memory is per-account, so a rule you teach it will not reach your teammates. ============================================================================== # Permissions URL: https://docs.dropstone.io/cli/permissions Description: Control which actions require approval to run. ============================================================================== Dropstone uses the `permission` config to decide whether a given action should run automatically, prompt you, or be blocked. The legacy `tools` boolean config is deprecated; it has been merged into `permission`. The old `tools` config is still supported for backwards compatibility. --- ## Actions Each permission rule resolves to one of: - `"allow"`: run without approval - `"ask"`: prompt for approval - `"deny"`: block the action --- ## Configuration You can set permissions globally (with `*`), and override specific tools. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "permission": { "*": "ask", "bash": "allow", "edit": "deny" } } ``` You can also set all permissions at once: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "permission": "allow" } ``` --- ## Granular Rules (Object Syntax) For most permissions, you can use an object to apply different actions based on the tool input. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "permission": { "bash": { "*": "ask", "git *": "allow", "npm *": "allow", "rm *": "deny", "grep *": "allow" }, "edit": { "*": "deny", "packages/web/src/content/docs/*.mdx": "allow" } } } ``` Rules are evaluated by pattern match, with the **last matching rule winning**. A common pattern is to put the catch-all `"*"` rule first, and more specific rules after it. ### Wildcards Permission patterns use simple wildcard matching: - `*` matches zero or more of any character - `?` matches exactly one character - All other characters match literally ### Home Directory Expansion You can use `~` or `$HOME` at the start of a pattern to reference your home directory. This is particularly useful for [`external_directory`](#external-directories) rules. - `~/projects/*` -> `/Users/username/projects/*` - `$HOME/projects/*` -> `/Users/username/projects/*` - `~` -> `/Users/username` ### External Directories Use `external_directory` to allow tool calls that touch paths outside the working directory where Dropstone was started. This applies to any tool that takes a path as input (for example `read`, `edit`, `glob`, `grep`, and many `bash` commands). Home expansion (like `~/...`) only affects how a pattern is written. It does not make an external path part of the current workspace, so paths outside the working directory must still be allowed via `external_directory`. For example, this allows access to everything under `~/projects/personal/`: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "permission": { "external_directory": { "~/projects/personal/**": "allow" } } } ``` Any directory allowed here inherits the same defaults as the current workspace. Since [`read` defaults to `allow`](#defaults), reads are also allowed for entries under `external_directory` unless overridden. Add explicit rules when a tool should be restricted in these paths, such as blocking edits while keeping reads: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "permission": { "external_directory": { "~/projects/personal/**": "allow" }, "edit": { "~/projects/personal/**": "deny" } } } ``` Keep the list focused on trusted paths, and layer extra allow or deny rules as needed for other tools (for example `bash`). --- ## Available Permissions Dropstone permissions are keyed by tool name, plus a couple of safety guards: - `read`: reading a file (matches the file path) - `edit`: all file modifications (covers `edit`, `write`, `patch`) - `glob`: file globbing (matches the glob pattern) - `grep`: content search (matches the regex pattern) - `bash`: running shell commands (matches parsed commands like `git status --porcelain`) - `task`: launching subagents (matches the subagent type) - `skill`: loading a skill (matches the skill name) - `lsp`: running LSP queries (currently non-granular) - `question`: asking the user questions during execution - `webfetch`: fetching a URL (matches the URL) - `websearch`: web search (matches the query) - `external_directory`: triggered when a tool touches paths outside the project working directory - `doom_loop`: triggered when the same tool call repeats 3 times with identical input --- ## Defaults If you don't specify anything, Dropstone starts from permissive defaults: - Most permissions default to `"allow"`. - `doom_loop` and `external_directory` default to `"ask"`. - `read` is `"allow"`, but `.env` files are denied by default: ```json title="dropstone.json" { "permission": { "read": { "*": "allow", "*.env": "deny", "*.env.*": "deny", "*.env.example": "allow" } } } ``` --- ## What "Ask" does When Dropstone prompts for approval, the UI offers three outcomes: - `once`: approve just this request - `always`: approve future requests matching the suggested patterns (for the rest of the current Dropstone session) - `reject`: deny the request The set of patterns that `always` would approve is provided by the tool (for example, bash approvals typically whitelist a safe command prefix like `git status*`). --- ## Agents You can override permissions per agent. Agent permissions are merged with the global config, and agent rules take precedence. [Learn more](./agents#permissions) about agent permissions. Refer to the [Granular Rules (Object Syntax)](#granular-rules-object-syntax) section above for more detailed pattern matching examples. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "permission": { "bash": { "*": "ask", "git *": "allow", "git commit *": "deny", "git push *": "deny", "grep *": "allow" } }, "agent": { "build": { "permission": { "bash": { "*": "ask", "git *": "allow", "git commit *": "ask", "git push *": "deny", "grep *": "allow" } } } } } ``` You can also configure agent permissions in Markdown: ```markdown title="~/.config/dropstone/agents/review.md" --- description: Code review without edits mode: subagent permission: edit: deny bash: ask webfetch: deny --- Only analyze code and suggest changes. ``` Use pattern matching for commands with arguments. `"grep *"` allows `grep pattern file.txt`, while `"grep"` alone would block it. Commands like `git status` work for default behavior but require explicit permission (like `"git status *"`) when arguments are passed. ============================================================================== # Agent Skills URL: https://docs.dropstone.io/cli/skills Description: Define reusable behavior via SKILL.md definitions ============================================================================== Agent skills let Dropstone discover reusable instructions from your repo or home directory. Skills are loaded on-demand via the built-in `skill` tool: agents see what skills are available and can load the full content when one matches the task. --- ## Place files Create one folder per skill name and put a `SKILL.md` inside it. Dropstone searches these locations: - Project config: `.dropstone/skills//SKILL.md` - Global config: `~/.config/dropstone/skills//SKILL.md` - Project Claude-compatible: `.claude/skills//SKILL.md` - Global Claude-compatible: `~/.claude/skills//SKILL.md` - Project agent-compatible: `.agents/skills//SKILL.md` - Global agent-compatible: `~/.agents/skills//SKILL.md` --- ## Understand discovery For project-local paths, Dropstone walks up from your current working directory until it reaches the git worktree. It loads any matching `skills/*/SKILL.md` in `.dropstone/` and any matching `.claude/skills/*/SKILL.md` or `.agents/skills/*/SKILL.md` along the way. Global definitions are also loaded from `~/.config/dropstone/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`, and `~/.agents/skills/*/SKILL.md`. --- ## Write frontmatter Each `SKILL.md` must start with YAML frontmatter. Only these fields are recognized: - `name` (required) - `description` (required) - `license` (optional) - `compatibility` (optional) - `metadata` (optional, string-to-string map) Unknown frontmatter fields are ignored. --- ## Validate names `name` must: - Be 1–64 characters - Be lowercase alphanumeric with single hyphen separators - Not start or end with `-` - Not contain consecutive `--` - Match the directory name that contains `SKILL.md` Equivalent regex: ```text ^[a-z0-9]+(-[a-z0-9]+)*$ ``` --- ## Follow length rules `description` must be 1-1024 characters. Keep it specific enough for the agent to choose correctly. --- ## Use an example Create `.dropstone/skills/git-release/SKILL.md` like this: ```markdown --- name: git-release description: Create consistent releases and changelogs license: MIT compatibility: dropstone metadata: audience: maintainers workflow: github --- ## What I do - Draft release notes from merged PRs - Propose a version bump - Provide a copy-pasteable `gh release create` command ## When to use me Use this when you are preparing a tagged release. Ask clarifying questions if the target versioning scheme is unclear. ``` --- ## Recognize tool description Dropstone lists available skills in the `skill` tool description. Each entry includes the skill name and description: ```xml git-release Create consistent releases and changelogs ``` The agent loads a skill by calling the tool: ``` skill({ name: "git-release" }) ``` --- ## Configure permissions Control which skills agents can access using pattern-based permissions in `dropstone.json`: ```json { "permission": { "skill": { "*": "allow", "pr-review": "allow", "internal-*": "deny", "experimental-*": "ask" } } } ``` | Permission | Behavior | | ---------- | ----------------------------------------- | | `allow` | Skill loads immediately | | `deny` | Skill hidden from agent, access rejected | | `ask` | User prompted for approval before loading | Patterns support wildcards: `internal-*` matches `internal-docs`, `internal-tools`, etc. --- ## Override per agent Give specific agents different permissions than the global defaults. **For custom agents** (in agent frontmatter): ```yaml --- permission: skill: "documents-*": "allow" --- ``` **For built-in agents** (in `dropstone.json`): ```json { "agent": { "plan": { "permission": { "skill": { "internal-*": "allow" } } } } } ``` --- ## Disable the skill tool Completely disable skills for agents that shouldn't use them: **For custom agents**: ```yaml --- tools: skill: false --- ``` **For built-in agents**: ```json { "agent": { "plan": { "tools": { "skill": false } } } } ``` When disabled, the `` section is omitted entirely. --- ## Troubleshoot loading If a skill does not show up: 1. Verify `SKILL.md` is spelled in all caps 2. Check that frontmatter includes `name` and `description` 3. Ensure skill names are unique across all locations 4. Check permissions: skills with `deny` are hidden from agents ============================================================================== # Plugins URL: https://docs.dropstone.io/cli/plugins Description: Write your own plugins to extend Dropstone. ============================================================================== Plugins allow you to extend Dropstone by hooking into various events and customizing behavior. You can create plugins to add new features, integrate with external services, or modify Dropstone's default behavior. --- ## Use a plugin There are two ways to load plugins. --- ### From local files Place JavaScript or TypeScript files in the plugin directory. - `.dropstone/plugins/` - Project-level plugins - `~/.config/dropstone/plugins/` - Global plugins Files in these directories are automatically loaded at startup. --- ### From npm Specify npm packages in your config file. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "plugin": ["@my-org/internal-plugin", "dropstone-notify-on-idle"] } ``` Both regular and scoped npm packages are supported. --- ### How plugins are installed **npm plugins** are installed automatically using Bun at startup. Packages and their dependencies are cached in `~/.cache/dropstone/node_modules/`. **Local plugins** are loaded directly from the plugin directory. To use external packages, you must create a `package.json` within your config directory (see [Dependencies](#dependencies)), or publish the plugin to npm and [add it to your config](./config#plugins). --- ### Load order Plugins are loaded from all sources and all hooks run in sequence. The load order is: 1. Global config (`~/.config/dropstone/dropstone.json`) 2. Project config (`dropstone.json`) 3. Global plugin directory (`~/.config/dropstone/plugins/`) 4. Project plugin directory (`.dropstone/plugins/`) Duplicate npm packages with the same name and version are loaded once. However, a local plugin and an npm plugin with similar names are both loaded separately. --- ## Create a plugin A plugin is a **JavaScript/TypeScript module** that exports one or more plugin functions. Each function receives a context object and returns a hooks object. --- ### Dependencies Local plugins and custom tools can use external npm packages. Add a `package.json` to your config directory with the dependencies you need. ```json title=".dropstone/package.json" { "dependencies": { "shescape": "^2.1.0" } } ``` Dropstone runs `bun install` at startup to install these. Your plugins and tools can then import them. ```ts title=".dropstone/plugins/my-plugin.ts" import { escape } from "shescape" export const MyPlugin = async (ctx) => { return { "tool.execute.before": async (input, output) => { if (input.tool === "bash") { output.args.command = escape(output.args.command) } }, } } ``` --- ### Basic structure ```js title=".dropstone/plugins/example.js" export const MyPlugin = async ({ project, client, $, directory, worktree }) => { console.log("Plugin initialized!") return { // Hook implementations go here } } ``` The plugin function receives: - `project`: The current project information. - `directory`: The current working directory. - `worktree`: The git worktree path. - `client`: A Dropstone SDK client for interacting with the agent. - `$`: Bun's [shell API](https://bun.com/docs/runtime/shell) for executing commands. --- ### TypeScript support For TypeScript plugins, you can import types from the plugin package: ```ts title="my-plugin.ts" {1} import type { Plugin } from "@blankline/dropstone-plugin" export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => { return { // Type-safe hook implementations } } ``` --- ### Events Plugins can subscribe to events as seen below in the Examples section. Here is a list of the different events available. #### Command Events - `command.executed` #### File Events - `file.edited` - `file.watcher.updated` #### Installation Events - `installation.updated` #### LSP Events - `lsp.client.diagnostics` - `lsp.updated` #### Message Events - `message.part.removed` - `message.part.updated` - `message.removed` - `message.updated` #### Permission Events - `permission.asked` - `permission.replied` #### Server Events - `server.connected` #### Session Events - `session.created` - `session.compacted` - `session.deleted` - `session.diff` - `session.error` - `session.idle` - `session.status` - `session.updated` #### Todo Events - `todo.updated` #### Shell Events - `shell.env` #### Tool Events - `tool.execute.after` - `tool.execute.before` --- ## Examples Here are some examples of plugins you can use to extend dropstone. --- ### Send notifications Send notifications when certain events occur: ```js title=".dropstone/plugins/notification.js" export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => { return { event: async ({ event }) => { // Send notification on session completion if (event.type === "session.idle") { await $`osascript -e 'display notification "Session completed!" with title "dropstone"'` } }, } } ``` We are using `osascript` to run AppleScript on macOS. Here we are using it to send notifications. --- ### .env protection Prevent dropstone from reading `.env` files: ```javascript title=".dropstone/plugins/env-protection.js" export const EnvProtection = async ({ project, client, $, directory, worktree }) => { return { "tool.execute.before": async (input, output) => { if (input.tool === "read" && output.args.filePath.includes(".env")) { throw new Error("Do not read .env files") } }, } } ``` --- ### Inject environment variables Inject environment variables into all shell execution (AI tools and user terminals): ```javascript title=".dropstone/plugins/inject-env.js" export const InjectEnvPlugin = async () => { return { "shell.env": async (input, output) => { output.env.MY_API_KEY = "secret" output.env.PROJECT_ROOT = input.cwd }, } } ``` --- ### Custom tools Plugins can also add custom tools to dropstone: ```ts title=".dropstone/plugins/custom-tools.ts" import { type Plugin, tool } from "@blankline/dropstone-plugin" export const CustomToolsPlugin: Plugin = async (ctx) => { return { tool: { mytool: tool({ description: "This is a custom tool", args: { foo: tool.schema.string(), }, async execute(args, context) { const { directory, worktree } = context return `Hello ${args.foo} from ${directory} (worktree: ${worktree})` }, }), }, } } ``` The `tool` helper creates a custom tool that dropstone can call. It takes a Zod schema function and returns a tool definition with: - `description`: What the tool does - `args`: Zod schema for the tool's arguments - `execute`: Function that runs when the tool is called Your custom tools will be available to dropstone alongside built-in tools. If a plugin tool uses the same name as a built-in tool, the plugin tool takes precedence. --- ### Logging Use `client.app.log()` instead of `console.log` for structured logging: ```ts title=".dropstone/plugins/my-plugin.ts" export const MyPlugin = async ({ client }) => { await client.app.log({ body: { service: "my-plugin", level: "info", message: "Plugin initialized", extra: { foo: "bar" }, }, }) } ``` Levels: `debug`, `info`, `warn`, `error`. See the [SDK reference](./sdk) for details. --- ### Compaction hooks Customize the context included when a session is compacted: ```ts title=".dropstone/plugins/compaction.ts" import type { Plugin } from "@blankline/dropstone-plugin" export const CompactionPlugin: Plugin = async (ctx) => { return { "experimental.session.compacting": async (input, output) => { // Inject additional context into the compaction prompt output.context.push(` ## Custom Context Include any state that should persist across compaction: - Current task status - Important decisions made - Files being actively worked on `) }, } } ``` The `experimental.session.compacting` hook fires before the LLM generates a continuation summary. Use it to inject domain-specific context that the default compaction prompt would miss. You can also replace the compaction prompt entirely by setting `output.prompt`: ```ts title=".dropstone/plugins/custom-compaction.ts" import type { Plugin } from "@blankline/dropstone-plugin" export const CustomCompactionPlugin: Plugin = async (ctx) => { return { "experimental.session.compacting": async (input, output) => { // Replace the entire compaction prompt output.prompt = ` You are generating a continuation prompt for a long-running coding session. Summarize: 1. The current task and its status 2. Which files are being modified 3. Any blockers or open questions 4. The next steps to complete the work Format as a structured prompt the next session can use to resume work. ` }, } } ``` When `output.prompt` is set, it completely replaces the default compaction prompt. The `output.context` array is ignored in this case. ============================================================================== # Custom Tools URL: https://docs.dropstone.io/cli/custom-tools Description: Create tools the LLM can call in dropstone. ============================================================================== Custom tools are functions you create that the LLM can call during conversations. They work alongside Dropstone's [built-in tools](./tools) like `read`, `write`, and `bash`. --- ## Creating a tool Tools are defined as **TypeScript** or **JavaScript** files. The tool definition itself is TS/JS, but the work it does can be implemented in **any language**: shell scripts, Python, Go, anything you can spawn from Bun's shell helpers. --- ### Location They can be defined: - Locally by placing them in the `.dropstone/tools/` directory of your project. - Or globally, by placing them in `~/.config/dropstone/tools/`. --- ### Structure The easiest way to create tools is using the `tool()` helper which provides type-safety and validation. ```ts title=".dropstone/tools/database.ts" {1} import { tool } from "@blankline/dropstone-plugin" export default tool({ description: "Query the project database", args: { query: tool.schema.string().describe("SQL query to execute"), }, async execute(args) { // Your database logic here return `Executed query: ${args.query}` }, }) ``` The **filename** becomes the **tool name**. The above creates a `database` tool. --- #### Multiple tools per file You can also export multiple tools from a single file. Each export becomes **a separate tool** with the name **`_`**: ```ts title=".dropstone/tools/math.ts" import { tool } from "@blankline/dropstone-plugin" export const add = tool({ description: "Add two numbers", args: { a: tool.schema.number().describe("First number"), b: tool.schema.number().describe("Second number"), }, async execute(args) { return args.a + args.b }, }) export const multiply = tool({ description: "Multiply two numbers", args: { a: tool.schema.number().describe("First number"), b: tool.schema.number().describe("Second number"), }, async execute(args) { return args.a * args.b }, }) ``` This creates two tools: `math_add` and `math_multiply`. --- #### Name collisions with built-in tools Custom tools are keyed by tool name. If a custom tool uses the same name as a built-in tool, the custom tool takes precedence. For example, this file replaces the built-in `bash` tool: ```ts title=".dropstone/tools/bash.ts" import { tool } from "@blankline/dropstone-plugin" export default tool({ description: "Restricted bash wrapper", args: { command: tool.schema.string(), }, async execute(args) { return `blocked: ${args.command}` }, }) ``` Prefer unique names unless you intentionally want to replace a built-in tool. If you want to disable a built-in tool but not override it, use [permissions](./permissions). --- ### Arguments You can use `tool.schema`, which is just [Zod](https://zod.dev), to define argument types. ```ts "tool.schema" args: { query: tool.schema.string().describe("SQL query to execute") } ``` You can also import [Zod](https://zod.dev) directly and return a plain object: ```ts {6} import { z } from "zod" export default { description: "Tool description", args: { param: z.string().describe("Parameter description"), }, async execute(args, context) { // Tool implementation return "result" }, } ``` --- ### Context Tools receive context about the current session: ```ts title=".dropstone/tools/project.ts" {8} import { tool } from "@blankline/dropstone-plugin" export default tool({ description: "Get project information", args: {}, async execute(args, context) { // Access context information const { agent, sessionID, messageID, directory, worktree } = context return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}, Directory: ${directory}, Worktree: ${worktree}` }, }) ``` Use `context.directory` for the session working directory. Use `context.worktree` for the git worktree root. --- ## Examples ### Write a tool in Python You can write your tools in any language you want. Here's an example that adds two numbers using Python. First, create the tool as a Python script: ```python title=".dropstone/tools/add.py" import sys a = int(sys.argv[1]) b = int(sys.argv[2]) print(a + b) ``` Then create the tool definition that invokes it: ```ts title=".dropstone/tools/python-add.ts" {10} import { tool } from "@blankline/dropstone-plugin" import path from "path" export default tool({ description: "Add two numbers using Python", args: { a: tool.schema.number().describe("First number"), b: tool.schema.number().describe("Second number"), }, async execute(args, context) { const script = path.join(context.worktree, ".dropstone/tools/add.py") const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text() return result.trim() }, }) ``` Here we are using the [`Bun.$`](https://bun.com/docs/runtime/shell) utility to run the Python script. ============================================================================== # Tools URL: https://docs.dropstone.io/cli/tools Description: Manage the tools an LLM can use. ============================================================================== Tools allow the LLM to perform actions in your codebase. Dropstone comes with a set of built-in tools, but you can extend it with [custom tools](./custom-tools) or [MCP servers](./mcp-servers). By default, all tools are **enabled** and don't need permission to run. You can control tool behavior through [permissions](./permissions). --- ## Configure Use the `permission` field to control tool behavior. You can allow, deny, or require approval for each tool. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "permission": { "edit": "deny", "bash": "ask", "webfetch": "allow" } } ``` You can also use wildcards to control multiple tools at once. For example, to require approval for all tools from an MCP server: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "permission": { "mymcp_*": "ask" } } ``` [Learn more](./permissions) about configuring permissions. --- ## Built-in Here are all the built-in tools available in Dropstone. --- ### bash Execute shell commands in your project environment. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "bash": "allow" } } ``` This tool allows the LLM to run terminal commands like `npm install`, `git status`, or any other shell command. --- ### edit Modify existing files using exact string replacements. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "edit": "allow" } } ``` This tool performs precise edits to files by replacing exact text matches. It's the primary way the LLM modifies code. --- ### write Create new files or overwrite existing ones. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "edit": "allow" } } ``` Use this to allow the LLM to create new files. It will overwrite existing files if they already exist. The `write` tool is controlled by the `edit` permission, which covers all file modifications (`edit`, `write`, `apply_patch`). --- ### read Read file contents from your codebase. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "read": "allow" } } ``` This tool reads files and returns their contents. It supports reading specific line ranges for large files. --- ### grep Search file contents using regular expressions. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "grep": "allow" } } ``` Fast content search across your codebase. Supports full regex syntax and file pattern filtering. --- ### glob Find files by pattern matching. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "glob": "allow" } } ``` Search for files using glob patterns like `**/*.js` or `src/**/*.ts`. Returns matching file paths sorted by modification time. --- ### lsp (experimental) Interact with your configured LSP servers to get code intelligence features like definitions, references, hover info, and call hierarchy. The LSP tool is experimental and disabled by default. Behaviour may change between releases. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "lsp": "allow" } } ``` Supported operations include `goToDefinition`, `findReferences`, `hover`, `documentSymbol`, `workspaceSymbol`, `goToImplementation`, `prepareCallHierarchy`, `incomingCalls`, and `outgoingCalls`. To configure which LSP servers are available for your project, see [LSP Servers](./lsp). --- ### apply_patch Apply patches to files. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "edit": "allow" } } ``` This tool applies patch files to your codebase. Useful for applying diffs and patches from various sources. When handling `tool.execute.before` or `tool.execute.after` hooks, check `input.tool === "apply_patch"` (not `"patch"`). `apply_patch` uses `output.args.patchText` instead of `output.args.filePath`. Paths are embedded in marker lines within `patchText` and are relative to the project root (for example: `*** Add File: src/new-file.ts`, `*** Update File: src/existing.ts`, `*** Move to: src/renamed.ts`, `*** Delete File: src/obsolete.ts`). The `apply_patch` tool is controlled by the `edit` permission, which covers all file modifications (`edit`, `write`, `apply_patch`). --- ### skill Load a [skill](./skills) (a `SKILL.md` file) and return its content in the conversation. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "skill": "allow" } } ``` --- ### todowrite Manage todo lists during coding sessions. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "todowrite": "allow" } } ``` Creates and updates task lists to track progress during complex operations. The LLM uses this to organize multi-step tasks. This tool is disabled for subagents by default, but you can enable it manually. [Learn more](./agents#permissions). --- ### webfetch Fetch web content. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "webfetch": "allow" } } ``` Allows the LLM to fetch and read web pages. Useful for looking up documentation or researching online resources. --- ### websearch Search the web for information. Available by default when you're signed in to Dropstone. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "websearch": "allow" } } ``` Performs web searches to find relevant information online. Useful for researching topics, finding current events, or gathering information beyond the training data cutoff. No API key or extra setup is required when you are signed in to Dropstone. Use `websearch` when you need to find information (discovery), and `webfetch` when you need to retrieve content from a specific URL (retrieval). --- ### question Ask the user questions during execution. ```json title="dropstone.json" {4} { "$schema": "https://dropstone.io/schema/config.json", "permission": { "question": "allow" } } ``` This tool allows the LLM to ask the user questions during a task. It's useful for: - Gathering user preferences or requirements - Clarifying ambiguous instructions - Getting decisions on implementation choices - Offering choices about what direction to take Each question includes a header, the question text, and a list of options. Users can select from the provided options or type a custom answer. When there are multiple questions, users can navigate between them before submitting all answers. --- ## Custom tools Custom tools let you define your own functions that the LLM can call. These are defined in your config file and can execute arbitrary code. [Learn more](./custom-tools) about creating custom tools. --- ## MCP servers MCP (Model Context Protocol) servers allow you to integrate external tools and services. This includes database access, API integrations, and third-party services. [Learn more](./mcp-servers) about configuring MCP servers. --- ## Ignore patterns By default, `grep` and `glob` respect your `.gitignore`: files and directories listed there are excluded from searches and listings. To include files that would normally be ignored, create a `.ignore` file in your project root. This file can explicitly allow certain paths. ```text title=".ignore" !node_modules/ !dist/ !build/ ``` For example, this `.ignore` file allows search within `node_modules/`, `dist/`, and `build/` directories even if they are listed in `.gitignore`. ============================================================================== # MCP servers URL: https://docs.dropstone.io/cli/mcp-servers Description: Add local and remote MCP tools. ============================================================================== You can add external tools to Dropstone using the _Model Context Protocol_, or MCP. Dropstone supports both local and remote servers. Once added, MCP tools are automatically available to the LLM alongside built-in tools. --- #### Caveats When you use an MCP server, it adds to the context. This can quickly add up if you have a lot of tools. So we recommend being careful with which MCP servers you use. MCP servers add to your context, so be careful with which ones you enable. Certain MCP servers, like the GitHub MCP server, tend to add a lot of tokens and can easily exceed the context limit. --- ## Enable You can define MCP servers in your [Dropstone config](./config) under `mcp`. Add each MCP with a unique name. You can refer to that MCP by name when prompting the LLM. ```json title="dropstone.jsonc" {6} { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "name-of-mcp-server": { // ... "enabled": true, }, "name-of-other-mcp-server": { // ... }, }, } ``` You can also disable a server by setting `enabled` to `false`. This is useful if you want to temporarily disable a server without removing it from your config. --- ### Overriding remote defaults Organizations can provide default MCP servers via their `.well-known/dropstone` endpoint. These servers may be disabled by default, allowing users to opt-in to the ones they need. To enable a specific server from your organization's remote config, add it to your local config with `enabled: true`: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "jira": { "type": "remote", "url": "https://jira.example.com/mcp", "enabled": true } } } ``` Your local config values override the remote defaults. See [config precedence](./config#precedence-order) for more details. --- ## Local Add local MCP servers using `type` to `"local"` within the MCP object. ```json title="dropstone.jsonc" {15} { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "my-local-mcp-server": { "type": "local", // Or ["bun", "x", "my-mcp-command"] "command": ["npx", "-y", "my-mcp-command"], "enabled": true, "environment": { "MY_ENV_VAR": "my_env_var_value", }, }, }, } ``` The command is how the local MCP server is started. You can also pass in a list of environment variables as well. For example, here's how you can add the test [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP server. ```json title="dropstone.jsonc" { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "mcp_everything": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-everything"], }, }, } ``` And to use it I can add `use the mcp_everything tool` to my prompts. ```txt "mcp_everything" use the mcp_everything tool to add the number 3 and 4 ``` --- #### Options Here are all the options for configuring a local MCP server. | Option | Type | Required | Description | | ------------- | ------- | -------- | ----------------------------------------------------------------------------------- | | `type` | String | Y | Type of MCP server connection, must be `"local"`. | | `command` | Array | Y | Command and arguments to run the MCP server. | | `environment` | Object | | Environment variables to set when running the server. | | `enabled` | Boolean | | Enable or disable the MCP server on startup. | | `timeout` | Number | | Timeout in ms for fetching tools from the MCP server. Defaults to 5000 (5 seconds). | --- ## Remote Add remote MCP servers by setting `type` to `"remote"`. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "my-remote-mcp": { "type": "remote", "url": "https://my-mcp-server.com", "enabled": true, "headers": { "Authorization": "Bearer MY_API_KEY" } } } } ``` The `url` is the URL of the remote MCP server and with the `headers` option you can pass in a list of headers. --- #### Options | Option | Type | Required | Description | | --------- | ------- | -------- | ----------------------------------------------------------------------------------- | | `type` | String | Y | Type of MCP server connection, must be `"remote"`. | | `url` | String | Y | URL of the remote MCP server. | | `enabled` | Boolean | | Enable or disable the MCP server on startup. | | `headers` | Object | | Headers to send with the request. | | `oauth` | Object | | OAuth authentication configuration. See [OAuth](#oauth) section below. | | `timeout` | Number | | Timeout in ms for fetching tools from the MCP server. Defaults to 5000 (5 seconds). | --- ## OAuth Dropstone automatically handles OAuth authentication for remote MCP servers. When a server requires authentication, Dropstone will: 1. Detect the 401 response and initiate the OAuth flow 2. Use **Dynamic Client Registration (RFC 7591)** if supported by the server 3. Store tokens securely for future requests --- ### Automatic For most OAuth-enabled MCP servers, no special configuration is needed. Just configure the remote server: ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "my-oauth-server": { "type": "remote", "url": "https://mcp.example.com/mcp" } } } ``` If the server requires authentication, Dropstone will prompt you to authenticate when you first try to use it. If not, you can [manually trigger the flow](#authenticating) with `dropstone mcp auth `. --- ### Pre-registered If you have client credentials from the MCP server provider, you can configure them: ```json title="dropstone.json" {7-11} { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "my-oauth-server": { "type": "remote", "url": "https://mcp.example.com/mcp", "oauth": { "clientId": "{env:MY_MCP_CLIENT_ID}", "clientSecret": "{env:MY_MCP_CLIENT_SECRET}", "scope": "tools:read tools:execute" } } } } ``` --- ### Authenticating You can manually trigger authentication or manage credentials. Authenticate with a specific MCP server: ```bash dropstone mcp auth my-oauth-server ``` List all MCP servers and their auth status: ```bash dropstone mcp list ``` Remove stored credentials: ```bash dropstone mcp logout my-oauth-server ``` The `mcp auth` command will open your browser for authorization. After you authorize, Dropstone will store the tokens securely in `~/.local/share/dropstone/mcp-auth.json`. --- #### Disabling OAuth If you want to disable automatic OAuth for a server (e.g., for servers that use API keys instead), set `oauth` to `false`: ```json title="dropstone.json" {7} { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "my-api-key-server": { "type": "remote", "url": "https://mcp.example.com/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:MY_API_KEY}" } } } } ``` --- #### OAuth Options | Option | Type | Description | | -------------- | --------------- | -------------------------------------------------------------------------------- | | `oauth` | Object \| false | OAuth config object, or `false` to disable OAuth auto-detection. | | `clientId` | String | OAuth client ID. If not provided, dynamic client registration will be attempted. | | `clientSecret` | String | OAuth client secret, if required by the authorization server. | | `scope` | String | OAuth scopes to request during authorization. | #### Debugging If a remote MCP server is failing to authenticate, you can diagnose issues with: ```bash # View auth status for all OAuth-capable servers dropstone mcp auth list # Debug connection and OAuth flow for a specific server dropstone mcp debug my-oauth-server ``` The `mcp debug` command shows the current auth status, tests HTTP connectivity, and attempts the OAuth discovery flow. --- ## Manage Your MCPs are available as tools in Dropstone, alongside built-in tools. So you can manage them through the Dropstone config like any other tool. --- ### Global This means that you can enable or disable them globally. ```json title="dropstone.json" {14} { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "my-mcp-foo": { "type": "local", "command": ["bun", "x", "my-mcp-command-foo"] }, "my-mcp-bar": { "type": "local", "command": ["bun", "x", "my-mcp-command-bar"] } }, "tools": { "my-mcp-foo": false } } ``` We can also use a glob pattern to disable all matching MCPs. ```json title="dropstone.json" {14} { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "my-mcp-foo": { "type": "local", "command": ["bun", "x", "my-mcp-command-foo"] }, "my-mcp-bar": { "type": "local", "command": ["bun", "x", "my-mcp-command-bar"] } }, "tools": { "my-mcp*": false } } ``` Here we are using the glob pattern `my-mcp*` to disable all MCPs. --- ### Per agent If you have a large number of MCP servers you may want to only enable them per agent and disable them globally. To do this: 1. Disable it as a tool globally. 2. In your [agent config](./agents#permissions), enable the MCP server as a tool. ```json title="dropstone.json" {11, 14-18} { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "my-mcp": { "type": "local", "command": ["bun", "x", "my-mcp-command"], "enabled": true } }, "tools": { "my-mcp*": false }, "agent": { "my-agent": { "tools": { "my-mcp*": true } } } } ``` --- #### Glob patterns The glob pattern uses simple regex globbing patterns: - `*` matches zero or more of any character (e.g., `"my-mcp*"` matches `my-mcp_search`, `my-mcp_list`, etc.) - `?` matches exactly one character - All other characters match literally MCP server tools are registered with the server name as a prefix, so to disable all tools for a server use: ``` "mymcpservername_*": false ``` --- ## Examples Below are examples of some common MCP servers. [Get in touch](https://dropstone.io/contact) if you'd like another one documented. --- ### Sentry Add the [Sentry MCP server](https://mcp.sentry.dev) to interact with your Sentry projects and issues. ```json title="dropstone.json" {4-8} { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "sentry": { "type": "remote", "url": "https://mcp.sentry.dev/mcp", "oauth": {} } } } ``` After adding the configuration, authenticate with Sentry: ```bash dropstone mcp auth sentry ``` This will open a browser window to complete the OAuth flow and connect Dropstone to your Sentry account. Once authenticated, you can use Sentry tools in your prompts to query issues, projects, and error data. ```txt "use sentry" Show me the latest unresolved issues in my project. use sentry ``` --- ### Context7 Add the [Context7 MCP server](https://github.com/upstash/context7) to search through docs. ```json title="dropstone.json" {4-7} { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp" } } } ``` If you have signed up for a free account, you can use your API key and get higher rate-limits. ```json title="dropstone.json" {7-9} { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp", "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" } } } } ``` Here we are assuming that you have the `CONTEXT7_API_KEY` environment variable set. Add `use context7` to your prompts to use Context7 MCP server. ```txt "use context7" Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7 ``` Alternatively, you can add something like this to your [AGENTS.md](./rules). ```md title="AGENTS.md" When you need to search docs, use `context7` tools. ``` --- ### Grep by Vercel Add the [Grep by Vercel](https://grep.app) MCP server to search through code snippets on GitHub. ```json title="dropstone.json" {4-7} { "$schema": "https://dropstone.io/schema/config.json", "mcp": { "gh_grep": { "type": "remote", "url": "https://mcp.grep.app" } } } ``` Since we named our MCP server `gh_grep`, you can add `use the gh_grep tool` to your prompts to get the agent to use it. ```txt "use the gh_grep tool" What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool ``` Alternatively, you can add something like this to your [AGENTS.md](./rules). ```md title="AGENTS.md" If you are unsure how to do something, use `gh_grep` to search code examples from GitHub. ``` ============================================================================== # LSP Servers URL: https://docs.dropstone.io/cli/lsp Description: Dropstone integrates with your LSP servers. ============================================================================== Dropstone can integrate with your Language Server Protocol (LSP) to help the LLM interact with your codebase. It uses diagnostics to provide feedback to the LLM. --- ## Built-in Dropstone comes with several built-in LSP servers for popular languages: | LSP Server | Extensions | Requirements | | ------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------ | | astro | .astro | Auto-installs for Astro projects | | bash | .sh, .bash, .zsh, .ksh | Auto-installs bash-language-server | | clangd | .c, .cpp, .cc, .cxx, .c++, .h, .hpp, .hh, .hxx, .h++ | Auto-installs for C/C++ projects | | csharp | .cs, .csx | `.NET SDK` installed | | clojure-lsp | .clj, .cljs, .cljc, .edn | `clojure-lsp` command available | | dart | .dart | `dart` command available | | deno | .ts, .tsx, .js, .jsx, .mjs | `deno` command available (auto-detects deno.json/deno.jsonc) | | elixir-ls | .ex, .exs | `elixir` command available | | eslint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue | `eslint` dependency in project | | fsharp | .fs, .fsi, .fsx, .fsscript | `.NET SDK` installed | | gleam | .gleam | `gleam` command available | | gopls | .go | `go` command available | | hls | .hs, .lhs | `haskell-language-server-wrapper` command available | | jdtls | .java | `Java SDK (version 21+)` installed | | julials | .jl | `julia` and `LanguageServer.jl` installed | | kotlin-ls | .kt, .kts | Auto-installs for Kotlin projects | | lua-ls | .lua | Auto-installs for Lua projects | | nixd | .nix | `nixd` command available | | ocaml-lsp | .ml, .mli | `ocamllsp` command available | | oxlint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelte | `oxlint` dependency in project | | php intelephense | .php | Auto-installs for PHP projects | | prisma | .prisma | `prisma` command available | | pyright | .py, .pyi | `pyright` dependency installed | | razor | .razor, .cshtml | `.NET SDK` and VS Code C# extension installed | | ruby-lsp (rubocop) | .rb, .rake, .gemspec, .ru | `ruby` and `gem` commands available | | rust | .rs | `rust-analyzer` command available | | sourcekit-lsp | .swift, .objc, .objcpp | `swift` installed (`xcode` on macOS) | | svelte | .svelte | Auto-installs for Svelte projects | | terraform | .tf, .tfvars | Auto-installs from GitHub releases | | tinymist | .typ, .typc | Auto-installs from GitHub releases | | typescript | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts | `typescript` dependency in project | | vue | .vue | Auto-installs for Vue projects | | yaml-ls | .yaml, .yml | Auto-installs Red Hat yaml-language-server | | zls | .zig, .zon | `zig` command available | When LSP is enabled, servers start when one of the above file extensions is detected and the requirements are met. --- ## How It Works When LSP is enabled and dropstone opens a file, it: 1. Checks the file extension against all enabled LSP servers. 2. Starts the appropriate LSP server if not already running. --- ## Configure You can enable and customize LSP servers through the `lsp` section in your dropstone config. To enable all built-in LSP servers, set `lsp` to `true`. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "lsp": true } ``` Use an object to keep built-ins enabled while configuring overrides or custom servers. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "lsp": {} } ``` Each configured LSP server entry supports the following: Server entries need `command` unless they only disable a server. | Property | Type | Description | | ---------------- | -------- | ------------------------------------------------- | | `disabled` | boolean | Set this to `true` to disable the LSP server | | `command` | string[] | The command to start the LSP server | | `extensions` | string[] | File extensions this LSP server should handle | | `env` | object | Environment variables to set when starting server | | `initialization` | object | Initialization options to send to the LSP server | Let's look at some examples. --- ### Environment variables Use the `env` property to set environment variables when starting the LSP server: ```json title="dropstone.json" {5-8} { "$schema": "https://dropstone.io/schema/config.json", "lsp": { "rust": { "command": ["rust-analyzer"], "env": { "RUST_LOG": "debug" } } } } ``` --- ### Initialization options Use the `initialization` property to pass initialization options to the LSP server. These are server-specific settings sent during the LSP `initialize` request: ```json title="dropstone.json" {5-13} { "$schema": "https://dropstone.io/schema/config.json", "lsp": { "custom-lsp": { "command": ["custom-lsp-server", "--stdio"], "extensions": [".custom"], "initialization": { "preferences": { "importModuleSpecifierPreference": "relative" } } } } } ``` Initialization options vary by LSP server. Check your LSP server's documentation for available options. --- ### Disabling LSP servers If `lsp` is omitted, all LSP servers are disabled. To disable all LSP servers after another config enabled them, set `lsp` to `false`: ```json title="dropstone.json" {3} { "$schema": "https://dropstone.io/schema/config.json", "lsp": false } ``` To disable a **specific** LSP server, set `disabled` to `true`: ```json title="dropstone.json" {5} { "$schema": "https://dropstone.io/schema/config.json", "lsp": { "typescript": { "disabled": true } } } ``` --- ### Custom LSP servers You can add custom LSP servers by specifying the command and file extensions: ```json title="dropstone.json" {4-7} { "$schema": "https://dropstone.io/schema/config.json", "lsp": { "custom-lsp": { "command": ["custom-lsp-server", "--stdio"], "extensions": [".custom"] } } } ``` --- ## Additional Information ### PHP Intelephense PHP Intelephense offers premium features through a license key. You can provide a license key by placing (only) the key in a text file at: - On macOS/Linux: `$HOME/intelephense/license.txt` - On Windows: `%USERPROFILE%/intelephense/license.txt` The file should contain only the license key with no additional content. ============================================================================== # Formatters URL: https://docs.dropstone.io/cli/formatters Description: Dropstone uses language specific formatters. ============================================================================== Dropstone can format files after they are written or edited using language-specific formatters. Formatters are disabled by default; enable them in your config before Dropstone will run them. --- ## Built-in Dropstone comes with several built-in formatters for popular languages and frameworks. Below is a list of the formatters, supported file extensions, and commands or config options it needs. | Formatter | Extensions | Requirements | | -------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | air | .R | `air` command available | | biome | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and [more](https://biomejs.dev/) | `biome.json(c)` config file | | cargofmt | .rs | `cargo fmt` command available | | clang-format | .c, .cpp, .h, .hpp, .ino, and [more](https://clang.llvm.org/docs/ClangFormat.html) | `.clang-format` config file | | cljfmt | .clj, .cljs, .cljc, .edn | `cljfmt` command available | | dart | .dart | `dart` command available | | dfmt | .d | `dfmt` command available | | gleam | .gleam | `gleam` command available | | gofmt | .go | `gofmt` command available | | htmlbeautifier | .erb, .html.erb | `htmlbeautifier` command available | | ktlint | .kt, .kts | `ktlint` command available | | mix | .ex, .exs, .eex, .heex, .leex, .neex, .sface | `mix` command available | | nixfmt | .nix | `nixfmt` command available | | ocamlformat | .ml, .mli | `ocamlformat` command available and `.ocamlformat` config file | | ormolu | .hs | `ormolu` command available | | pint | .php | `laravel/pint` dependency in `composer.json` | | prettier | .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml, and [more](https://prettier.io/docs/en/index.html) | `prettier` dependency in `package.json` | | rubocop | .rb, .rake, .gemspec, .ru | `rubocop` command available | | ruff | .py, .pyi | `ruff` command available with config | | rustfmt | .rs | `rustfmt` command available | | shfmt | .sh, .bash | `shfmt` command available | | standardrb | .rb, .rake, .gemspec, .ru | `standardrb` command available | | terraform | .tf, .tfvars | `terraform` command available | | uv | .py, .pyi | `uv` command available | | zig | .zig, .zon | `zig` command available | When formatters are enabled, Dropstone will use `prettier` for matching files if your project has `prettier` in `package.json`. --- ## How it works When Dropstone writes or edits a file and formatters are enabled, it: 1. Checks the file extension against all enabled formatters. 2. Runs the appropriate formatter command on the file. 3. Applies the formatting changes. This process happens in the background for enabled formatters. --- ## Configure You can enable and customize formatters through the `formatter` section in your Dropstone config. To enable all built-in formatters, set `formatter` to `true`. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "formatter": true } ``` Use an object to keep built-ins enabled while configuring overrides or custom formatters. ```json title="dropstone.json" { "$schema": "https://dropstone.io/schema/config.json", "formatter": {} } ``` Each formatter configuration supports the following: | Property | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------ | | `disabled` | boolean | Set this to `true` to disable the formatter | | `command` | string[] | The command to run for formatting. Required for custom formatters; optional for built-ins. | | `environment` | object | Environment variables to set when running the formatter | | `extensions` | string[] | File extensions this formatter should handle | Let's look at some examples. --- ### Disabling formatters If `formatter` is omitted, all formatters are disabled. To disable all formatters after another config enabled them, set `formatter` to `false`: ```json title="dropstone.json" {3} { "$schema": "https://dropstone.io/schema/config.json", "formatter": false } ``` To disable a **specific** formatter, set `disabled` to `true`: ```json title="dropstone.json" {5} { "$schema": "https://dropstone.io/schema/config.json", "formatter": { "prettier": { "disabled": true } } } ``` --- ### Custom formatters You can configure built-in formatters with options like `environment` or `extensions`. To add a custom formatter, specify a `command` and `extensions`: ```json title="dropstone.json" {4-14} { "$schema": "https://dropstone.io/schema/config.json", "formatter": { "prettier": { "command": ["npx", "prettier", "--write", "$FILE"], "environment": { "NODE_ENV": "development" }, "extensions": [".js", ".ts", ".jsx", ".tsx"] }, "custom-markdown-formatter": { "command": ["deno", "fmt", "$FILE"], "extensions": [".md"] } } } ``` The **`$FILE` placeholder** in the command will be replaced with the path to the file being formatted. ============================================================================== # Dropstone for VS Code - AI Coding Agent Extension URL: https://docs.dropstone.io/cli/vscode Description: Install the Dropstone extension for VS Code, Cursor, Windsurf and VSCodium. Get the full agent as a panel beside your code, with every edit shown as a reviewable diff. ============================================================================== Dropstone runs as an extension inside the editor you already use. There is no separate Dropstone IDE to install, no workspace to migrate, and nothing to learn twice — you add an extension and the agent appears beside your code. Get Dropstone for VS Code on the Marketplace It works in VS Code and the popular forks: **Cursor**, **Windsurf**, and **VSCodium**. --- ## Install Press `Cmd+Shift+X` on Mac, or `Ctrl+Shift+X` on Windows and Linux. Look for **Dropstone for VS Code**, published by **Blankline Official**. Publisher matters — install the one from Blankline Official. Click **Install**, then sign in with your Dropstone account. If you already use the CLI, it is the same account and the same weekly allowance. You can also install it straight from the [Marketplace listing](https://marketplace.visualstudio.com/items?itemName=blankline-org.dropstone) in your browser. --- ## What it does The extension is the full agent, not a chat box. It reads, writes and refactors code across your workspace, runs commands, and explains what it did afterwards. ### Every edit is a reviewable diff Nothing is written to your files until you say so. Each change arrives as a diff you can read, accept, or reject — so you always review the work before it lands, the same way you would review a colleague's pull request. ### Agent modes Choose how much autonomy the agent gets: | Mode | What it does | |---|---| | **Build** | Makes changes as it works, showing each one for review. | | **Plan** | Works out an approach and presents it before touching anything. | | **Accept All** | Applies changes without stopping for each diff. For work you already trust. | | **Discovery** | Explores and explains the codebase without editing it. | ### Model and effort control Switch between the Fast, Pro and Heavy tiers and adjust reasoning effort from inside the panel — no config file, no restart. See [Models](/cli/models) for what each tier is good at. ### Permissions Any tool call that touches your machine — running a command, writing outside the workspace — prompts first. The rules are the same ones described in [Permissions](/cli/permissions). ### Images and screenshots Paste a screenshot directly into the conversation. Useful for a failing UI, a stack trace in a terminal you cannot copy from, or a design you want built. ### Slash commands Both the built-in commands and any your workspace defines are available. See [Slash Commands](/cli/commands). ### Chat history Sessions can be resumed, renamed, or deleted, so a long-running piece of work survives closing the editor. --- ## Extension or CLI? They are the same agent with the same account, the same weekly usage window, and the same memory. Anything Dropstone learns in one is available in the other, and work in either counts against one allowance. The difference is only how you drive it: - **The extension** keeps you in the editor, and is the easier place to review diffs against the file they belong to. - **[The CLI](/cli/overview)** is better when you already live in a terminal, are working over SSH, or want to script it. See [IDE](/cli/ide) for running it inside your editor's integrated terminal. Use whichever fits the task. Many people use both. Signing in is what connects the extension to your plan. Without it there is no model access, and [memory](/cli/memory) is not loaded. ============================================================================== # IDE URL: https://docs.dropstone.io/cli/ide Description: Run the Dropstone CLI inside VS Code, Cursor, or any IDE with an integrated terminal. ============================================================================== Dropstone integrates with VS Code, Cursor, or any IDE that supports a terminal. Just run `dropstone` in the terminal to get started. Prefer the agent as a panel beside your code, with edits shown as reviewable diffs? Install [Dropstone for VS Code](/cli/vscode) instead. Same account, same weekly allowance, same memory — it is only a different way to drive it. --- ## Usage - **Quick Launch**: Use `Cmd+Esc` (Mac) or `Ctrl+Esc` (Windows/Linux) to open Dropstone in a split terminal view, or focus an existing terminal session if one is already running. - **New Session**: Use `Cmd+Shift+Esc` (Mac) or `Ctrl+Shift+Esc` (Windows/Linux) to start a new Dropstone terminal session, even if one is already open. You can also click the Dropstone button in the UI. - **Context Awareness**: Automatically share your current selection or tab with Dropstone. - **File Reference Shortcuts**: Use `Cmd+Option+K` (Mac) or `Alt+Ctrl+K` (Linux/Windows) to insert file references. For example, `@File#L37-42`. --- ## Installation To install Dropstone on VS Code and popular forks like Cursor, Windsurf, VSCodium: 1. Open VS Code 2. Open the integrated terminal 3. Run `dropstone` - the extension installs automatically If on the other hand you want to use your own IDE when you run `/editor` or `/export` from a Dropstone session, you'll need to set `export EDITOR="code --wait"`. [Learn more](/cli/session#editor-setup). --- ### Manual Install Search for **Dropstone** in the Extension Marketplace and click **Install**. --- ### Troubleshooting If the extension fails to install automatically: - Ensure you're running `dropstone` in the integrated terminal. - Confirm the CLI for your IDE is installed: - For VS Code: `code` command - For Cursor: `cursor` command - For Windsurf: `windsurf` command - For VSCodium: `codium` command - If not, run `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux) and search for "Shell Command: Install 'code' command in PATH" (or the equivalent for your IDE) - Ensure VS Code has permission to install extensions ============================================================================== # ACP Support URL: https://docs.dropstone.io/cli/acp Description: Use Dropstone in any ACP-compatible editor. ============================================================================== Dropstone supports the [Agent Client Protocol](https://agentclientprotocol.com) or (ACP), allowing you to use it directly in compatible editors and IDEs. For a list of editors and tools that support ACP, check out the [ACP progress report](https://zed.dev/blog/acp-progress-report#available-now). ACP is an open protocol that standardizes communication between code editors and AI coding agents. --- ## Configure To use Dropstone via ACP, configure your editor to run the `dropstone acp` command. The command starts Dropstone as an ACP-compatible subprocess that communicates with your editor over JSON-RPC via stdio. Below are examples for popular editors that support ACP. --- ### Zed Add to your [Zed](https://zed.dev) configuration (`~/.config/zed/settings.json`): ```json title="~/.config/zed/settings.json" { "agent_servers": { "Dropstone": { "command": "dropstone", "args": ["acp"] } } } ``` To open it, use the `agent: new thread` action in the **Command Palette**. You can also bind a keyboard shortcut by editing your `keymap.json`: ```json title="keymap.json" [ { "bindings": { "cmd-alt-o": [ "agent::NewExternalAgentThread", { "agent": { "custom": { "name": "Dropstone", "command": { "command": "dropstone", "args": ["acp"] } } } } ] } } ] ``` --- ### JetBrains IDEs Add to your [JetBrains IDE](https://www.jetbrains.com/) acp.json according to the [documentation](https://www.jetbrains.com/help/ai-assistant/acp.html): ```json title="acp.json" { "agent_servers": { "Dropstone": { "command": "/absolute/path/bin/dropstone", "args": ["acp"] } } } ``` To open it, use the new 'Dropstone' agent in the AI Chat agent selector. --- ### Avante.nvim Add to your [Avante.nvim](https://github.com/yetone/avante.nvim) configuration: ```lua { acp_providers = { ["dropstone"] = { command = "dropstone", args = { "acp" } } } } ``` If you need to pass environment variables: ```lua {6-8} { acp_providers = { ["dropstone"] = { command = "dropstone", args = { "acp" }, env = { DROPSTONE_API_KEY = os.getenv("DROPSTONE_API_KEY") } } } } ``` --- ### CodeCompanion.nvim To use Dropstone as an ACP agent in [CodeCompanion.nvim](https://github.com/olimorris/codecompanion.nvim), add the following to your Neovim config: ```lua require("codecompanion").setup({ interactions = { chat = { adapter = { name = "dropstone", model = "dropstone-pro", }, }, }, }) ``` This config sets up CodeCompanion to use Dropstone as the ACP agent for chat. If you need to pass environment variables (like `DROPSTONE_API_KEY`), refer to [Configuring Adapters: Environment Variables](https://codecompanion.olimorris.dev/getting-started#setting-an-api-key) in the CodeCompanion.nvim documentation for full details. ## Support Dropstone works the same via ACP as it does in the terminal. All features are supported: - Built-in tools (file operations, terminal commands, etc.) - Custom tools and slash commands - MCP servers configured in your Dropstone config - Project-specific rules from `AGENTS.md` - Custom formatters and linters - Agents and permissions system Some built-in slash commands like `/undo` and `/redo` are currently unsupported over ACP. ============================================================================== # GitHub URL: https://docs.dropstone.io/cli/github Description: Use Dropstone in GitHub issues and pull-requests. ============================================================================== Dropstone integrates with your GitHub workflow. Mention `/dropstone` in any comment and Dropstone will execute the task inside your GitHub Actions runner. --- ## Features - **Triage issues**: Ask Dropstone to look into an issue and explain it to you. - **Fix and implement**: Ask Dropstone to fix an issue or implement a feature. And it will work in a new branch and submits a PR with all the changes. - **Secure**: Dropstone runs inside your GitHub's runners. --- ## Installation Run the following command in a project that is in a GitHub repo: ```bash dropstone github install ``` This will walk you through installing the GitHub app, creating the workflow, and setting up secrets. --- ### Manual Setup Or you can set it up manually. 1. **Install the GitHub app** Head over to [**github.com/apps/dropstone-agent**](https://github.com/apps/dropstone-agent). Make sure it's installed on the target repository. 2. **Add the workflow** Add the following workflow file to `.github/workflows/dropstone.yml` in your repo. Make sure to set the appropriate `model` and required API keys in `env`. ```yml title=".github/workflows/dropstone.yml" {24,26} name: dropstone on: issue_comment: types: [created] pull_request_review_comment: types: [created] jobs: dropstone: if: contains(github.event.comment.body, '/dropstone') runs-on: ubuntu-latest permissions: id-token: write steps: - name: Checkout repository uses: actions/checkout@v6 with: fetch-depth: 1 persist-credentials: false - name: Run Dropstone uses: blankline-org/dropstone-cli/github@latest env: DROPSTONE_API_KEY: ${{ secrets.DROPSTONE_API_KEY }} with: model: dropstone/dropstone-pro # share: true # github_token: xxxx ``` 3. **Store your API key in repository secrets** In your organization or repository **Settings**, expand **Secrets and variables** on the left and select **Actions**. Add `DROPSTONE_API_KEY` as a new repository secret. --- ## Configuration - `model`: The Dropstone tier to use. One of `dropstone/dropstone-fast`, `dropstone/dropstone-pro`, or `dropstone/dropstone-heavy`. This is **required**. - `agent`: The agent to use. Must be a primary agent. Falls back to `default_agent` from config or `"build"` if not found. - `share`: Whether to share the Dropstone session. Defaults to **true** for public repositories. - `prompt`: Optional custom prompt to override the default behavior. Use this to customize how Dropstone processes requests. - `token`: Optional GitHub access token for performing operations such as creating comments, committing changes, and opening pull requests. By default, Dropstone uses the installation access token from the Dropstone GitHub App, so commits, comments, and pull requests appear as coming from the app. Alternatively, you can use the GitHub Action runner's [built-in `GITHUB_TOKEN`](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token) without installing the Dropstone GitHub App. Just make sure to grant the required permissions in your workflow: ```yaml permissions: id-token: write contents: write pull-requests: write issues: write ``` You can also use a [personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)(PAT) if preferred. --- ## Supported Events Dropstone can be triggered by the following GitHub events: | Event Type | Triggered By | Details | | ----------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `issue_comment` | Comment on an issue or PR | Mention `/dropstone` in your comment. Dropstone reads context and can create branches, open PRs, or reply. | | `pull_request_review_comment` | Comment on specific code lines in a PR | Mention `/dropstone` while reviewing code. Dropstone receives file path, line numbers, and diff context. | | `issues` | Issue opened or edited | Automatically trigger Dropstone when issues are created or modified. Requires `prompt` input. | | `pull_request` | PR opened or updated | Automatically trigger Dropstone when PRs are opened, synchronized, or reopened. Useful for automated reviews. | | `schedule` | Cron-based schedule | Run Dropstone on a schedule. Requires `prompt` input. Output goes to logs and PRs (no issue to comment on). | | `workflow_dispatch` | Manual trigger from GitHub UI | Trigger Dropstone on demand via Actions tab. Requires `prompt` input. Output goes to logs and PRs. | ### Schedule Example Run Dropstone on a schedule to perform automated tasks: ```yaml title=".github/workflows/dropstone-scheduled.yml" name: Scheduled Dropstone Task on: schedule: - cron: "0 9 * * 1" # Every Monday at 9am UTC jobs: dropstone: runs-on: ubuntu-latest permissions: id-token: write contents: write pull-requests: write issues: write steps: - name: Checkout repository uses: actions/checkout@v6 with: persist-credentials: false - name: Run Dropstone uses: blankline-org/dropstone-cli/github@latest env: DROPSTONE_API_KEY: ${{ secrets.DROPSTONE_API_KEY }} with: model: dropstone/dropstone-pro prompt: | Review the codebase for any TODO comments and create a summary. If you find issues worth addressing, open an issue to track them. ``` For scheduled events, the `prompt` input is **required** since there's no comment to extract instructions from. Scheduled workflows run without a user context to permission-check, so the workflow must grant `contents: write` and `pull-requests: write` if you expect Dropstone to create branches or PRs. --- ### Pull Request Example Automatically review PRs when they are opened or updated: ```yaml title=".github/workflows/dropstone-review.yml" name: dropstone-review on: pull_request: types: [opened, synchronize, reopened, ready_for_review] jobs: review: runs-on: ubuntu-latest permissions: id-token: write contents: read pull-requests: read issues: read steps: - uses: actions/checkout@v6 with: persist-credentials: false - uses: blankline-org/dropstone-cli/github@latest env: DROPSTONE_API_KEY: ${{ secrets.DROPSTONE_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: model: dropstone/dropstone-pro use_github_token: true prompt: | Review this pull request: - Check for code quality issues - Look for potential bugs - Suggest improvements ``` For `pull_request` events, if no `prompt` is provided, Dropstone defaults to reviewing the pull request. --- ### Issues Triage Example Automatically triage new issues. This example filters to accounts older than 30 days to reduce spam: ```yaml title=".github/workflows/dropstone-triage.yml" name: Issue Triage on: issues: types: [opened] jobs: triage: runs-on: ubuntu-latest permissions: id-token: write contents: write pull-requests: write issues: write steps: - name: Check account age id: check uses: actions/github-script@v7 with: script: | const user = await github.rest.users.getByUsername({ username: context.payload.issue.user.login }); const created = new Date(user.data.created_at); const days = (Date.now() - created) / (1000 * 60 * 60 * 24); return days >= 30; result-encoding: string - uses: actions/checkout@v6 if: steps.check.outputs.result == 'true' with: persist-credentials: false - uses: blankline-org/dropstone-cli/github@latest if: steps.check.outputs.result == 'true' env: DROPSTONE_API_KEY: ${{ secrets.DROPSTONE_API_KEY }} with: model: dropstone/dropstone-pro prompt: | Review this issue. If there's a clear fix or relevant docs: - Provide documentation links - Add error handling guidance for code examples Otherwise, do not comment. ``` For `issues` events, the `prompt` input is **required** since there's no comment to extract instructions from. --- ## Custom prompts Override the default prompt to customize Dropstone's behavior for your workflow. ```yaml title=".github/workflows/dropstone.yml" - uses: blankline-org/dropstone-cli/github@latest with: model: dropstone/dropstone-pro prompt: | Review this pull request: - Check for code quality issues - Look for potential bugs - Suggest improvements ``` This is useful for enforcing specific review criteria, coding standards, or focus areas relevant to your project. --- ## Examples Here are some examples of how you can use Dropstone in GitHub. - **Explain an issue** Add this comment in a GitHub issue. ``` /dropstone explain this issue ``` Dropstone will read the entire thread, including all comments, and reply with a clear explanation. - **Fix an issue** In a GitHub issue, say: ``` /dropstone fix this ``` And Dropstone will create a new branch, implement the changes, and open a PR with the changes. - **Review PRs and make changes** Leave the following comment on a GitHub PR. ``` /dropstone delete the attachment from S3 when the note is removed ``` Dropstone will implement the requested change and commit it to the same PR. - **Review specific code lines** Leave a comment directly on code lines in the PR's "Files" tab. Dropstone automatically detects the file, line numbers, and diff context to provide precise responses. ``` [Comment on specific lines in Files tab] /dropstone add error handling here ``` When commenting on specific lines, Dropstone receives: - The exact file being reviewed - The specific lines of code - The surrounding diff context - Line number information This allows for more targeted requests without needing to specify file paths or line numbers manually. ============================================================================== # GitLab URL: https://docs.dropstone.io/cli/gitlab Description: Use Dropstone in GitLab issues and merge requests. ============================================================================== Dropstone integrates with your GitLab workflow through your GitLab CI/CD pipeline or with GitLab Duo. In both cases, Dropstone will run on your GitLab runners. --- ## GitLab CI Dropstone works in a regular GitLab pipeline. You can build it into a pipeline as a [CI component](https://docs.gitlab.com/ee/ci/components/) Here we are using a community-created CI/CD component for Dropstone: [nagyv/gitlab-dropstone](https://gitlab.com/nagyv/gitlab-dropstone). --- ### Features - **Use custom configuration per job**: Configure Dropstone with a custom configuration directory, for example `./config/#custom-directory` to enable or disable functionality per Dropstone invocation. - **Minimal setup**: The CI component sets up Dropstone in the background, you only need to create the Dropstone configuration and the initial prompt. - **Flexible**: The CI component supports several inputs for customizing its behavior --- ### Setup 1. Store your Dropstone authentication JSON as a File type CI environment variables under **Settings** > **CI/CD** > **Variables**. Make sure to mark them as "Masked and hidden". 2. Add the following to your `.gitlab-ci.yml` file. ```yaml title=".gitlab-ci.yml" include: - component: $CI_SERVER_FQDN/nagyv/gitlab-dropstone/dropstone@2 inputs: config_dir: ${CI_PROJECT_DIR}/dropstone-config auth_json: $DROPSTONE_AUTH_JSON # The variable name for your Dropstone authentication JSON command: optional-custom-command message: "Your prompt here" ``` For more inputs and use cases [check out the docs](https://gitlab.com/explore/catalog/nagyv/gitlab-dropstone) for this component. --- ## GitLab Duo Dropstone integrates with your GitLab workflow. Mention `@dropstone` in a comment, and Dropstone will execute tasks within your GitLab CI pipeline. --- ### Features - **Triage issues**: Ask Dropstone to look into an issue and explain it to you. - **Fix and implement**: Ask Dropstone to fix an issue or implement a feature. It will create a new branch and raise a merge request with the changes. - **Secure**: Dropstone runs on your GitLab runners. --- ### Setup Dropstone runs in your GitLab CI/CD pipeline, here's what you'll need to set it up: Check out the [**GitLab docs**](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/) for up-to-date instructions. 1. Configure your GitLab environment 2. Set up CI/CD 3. Get a Dropstone API key (see [Quickstart](../getting-started/quick-start#step-2-sign-in)) 4. Create a service account 5. Configure CI/CD variables 6. Create a flow config file. Example: ```yaml image: node:22-slim commands: - echo "Installing Dropstone" - curl -fsSL https://dropstone.io/install | bash - echo "Installing glab" - export GITLAB_TOKEN=$GITLAB_TOKEN_DROPSTONE - apt-get update --quiet && apt-get install --yes curl wget gpg git && rm --recursive --force /var/lib/apt/lists/* - curl --silent --show-error --location "https://raw.githubusercontent.com/upciti/wakemeops/main/assets/install_repository" | bash - apt-get install --yes glab - echo "Configuring glab" - echo $GITLAB_HOST - echo "Creating Dropstone auth configuration" - mkdir --parents ~/.local/share/dropstone - | cat > ~/.local/share/dropstone/auth.json << EOF { "dropstone": { "type": "api", "key": "$DROPSTONE_API_KEY" } } EOF - echo "Configuring git" - git config --global user.email "dropstone@gitlab.com" - git config --global user.name "Dropstone" - echo "Testing glab" - glab issue list - echo "Running Dropstone" - | dropstone run " You are an AI assistant helping with GitLab operations. Context: $AI_FLOW_CONTEXT Task: $AI_FLOW_INPUT Event: $AI_FLOW_EVENT Please execute the requested task using the available GitLab tools. Be thorough in your analysis and provide clear explanations. Use the glab CLI to access data from GitLab. The glab CLI is already authenticated. If you are asked to summarize an MR or issue, or provide more information, post back a note to the MR/Issue so the user can see it. " - git checkout --branch $CI_WORKLOAD_REF origin/$CI_WORKLOAD_REF - echo "Checking for git changes and pushing if any exist" - | if ! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]; then echo "Git changes detected, adding and pushing..." git add . if git diff --cached --quiet; then echo "No staged changes to commit" else echo "Committing changes to branch: $CI_WORKLOAD_REF" git commit --message "Dropstone changes" echo "Pushing changes up to $CI_WORKLOAD_REF" git push "https://gitlab-ci-token:$GITLAB_TOKEN@$GITLAB_HOST/$CI_PROJECT_PATH.git" $CI_WORKLOAD_REF echo "Changes successfully pushed" fi else echo "No git changes detected, skipping push" fi variables: - DROPSTONE_API_KEY - GITLAB_TOKEN_DROPSTONE - GITLAB_HOST ``` You can refer to the [GitLab Duo Agent Platform docs](https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/) for detailed instructions. --- ### Examples Here are some examples of how you can use Dropstone in GitLab. You can configure a different trigger phrase than `@dropstone`. - **Explain an issue** Add this comment in a GitLab issue. ``` @dropstone explain this issue ``` Dropstone will read the issue and reply with a clear explanation. - **Fix an issue** In a GitLab issue, say: ``` @dropstone fix this ``` Dropstone will create a new branch, implement the changes, and open a merge request with the changes. - **Review merge requests** Leave the following comment on a GitLab merge request. ``` @dropstone review this merge request ``` Dropstone will review the merge request and provide feedback. ============================================================================== # Server URL: https://docs.dropstone.io/cli/server Description: Interact with dropstone server over HTTP. ============================================================================== The `dropstone serve` command runs a headless HTTP server that exposes an OpenAPI endpoint a Dropstone client can use. --- ### Usage ```bash dropstone serve [--port ] [--hostname ] [--cors ] ``` #### Options | Flag | Description | Default | | --------------- | ----------------------------------- | ---------------- | | `--port` | Port to listen on | `4096` | | `--hostname` | Hostname to listen on | `127.0.0.1` | | `--mdns` | Enable mDNS discovery | `false` | | `--mdns-domain` | Custom domain name for mDNS service | `dropstone.local` | | `--cors` | Additional browser origins to allow | `[]` | `--cors` can be passed multiple times: ```bash dropstone serve --cors http://localhost:5173 --cors https://app.example.com ``` --- ### Authentication Set `DROPSTONE_SERVER_PASSWORD` to protect the server with HTTP basic auth. The username defaults to `dropstone`, or set `DROPSTONE_SERVER_USERNAME` to override it. This applies to both `dropstone serve` and `dropstone web`. ```bash DROPSTONE_SERVER_PASSWORD=your-password dropstone serve ``` --- ### How it works `dropstone serve` exposes Dropstone's capabilities over an OpenAPI 3.1 HTTP endpoint. The same endpoint is used to generate the [SDK](./sdk). Use the server when you want to drive Dropstone programmatically: from a script, a CI pipeline, or an integration of your own. The interactive session and the server are independent. Running `dropstone serve` starts a fresh standalone server regardless of whether you have an interactive session open. You can override the bind address with the `--hostname` and `--port` [flags](./cli). --- ## Spec The server publishes an OpenAPI 3.1 spec that can be viewed at: ``` http://:/doc ``` For example, `http://localhost:4096/doc`. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer. --- ## APIs The dropstone server exposes the following APIs. --- ### Global | Method | Path | Description | Response | | ------ | ---------------- | ------------------------------ | ------------------------------------ | | `GET` | `/global/health` | Get server health and version | `{ healthy: true, version: string }` | | `GET` | `/global/event` | Get global events (SSE stream) | Event stream | --- ### Project | Method | Path | Description | Response | | ------ | ------------------ | ----------------------- | --------------------------------------------- | | `GET` | `/project` | List all projects | Project[] | | `GET` | `/project/current` | Get the current project | Project | --- ### Path & VCS | Method | Path | Description | Response | | ------ | ------- | ------------------------------------ | ------------------------------------------- | | `GET` | `/path` | Get the current path | Path | | `GET` | `/vcs` | Get VCS info for the current project | VcsInfo | --- ### Config | Method | Path | Description | Response | | ------- | --------- | --------------- | ----------------------------------------- | | `GET` | `/config` | Get config info | Config | | `PATCH` | `/config` | Update config | Config | --- ### Sessions | Method | Path | Description | Notes | | -------- | ---------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------- | | `GET` | `/session` | List all sessions | Returns Session[] | | `POST` | `/session` | Create a new session | body: `{ parentID?, title? }`, returns Session | | `GET` | `/session/status` | Get session status for all sessions | Returns `{ [sessionID: string]: `SessionStatus` }` | | `GET` | `/session/:id` | Get session details | Returns Session | | `DELETE` | `/session/:id` | Delete a session and all its data | Returns `boolean` | | `PATCH` | `/session/:id` | Update session properties | body: `{ title? }`, returns Session | | `GET` | `/session/:id/children` | Get a session's child sessions | Returns Session[] | | `GET` | `/session/:id/todo` | Get the todo list for a session | Returns Todo[] | | `POST` | `/session/:id/init` | Analyze app and create `AGENTS.md` | body: `{ messageID, providerID, modelID }`, returns `boolean` | | `POST` | `/session/:id/fork` | Fork an existing session at a message | body: `{ messageID? }`, returns Session | | `POST` | `/session/:id/abort` | Abort a running session | Returns `boolean` | | `GET` | `/session/:id/diff` | Get the diff for this session | query: `messageID?`, returns FileDiff[] | | `POST` | `/session/:id/summarize` | Summarize the session | body: `{ providerID, modelID }`, returns `boolean` | | `POST` | `/session/:id/revert` | Revert a message | body: `{ messageID, partID? }`, returns `boolean` | | `POST` | `/session/:id/unrevert` | Restore all reverted messages | Returns `boolean` | | `POST` | `/session/:id/permissions/:permissionID` | Respond to a permission request | body: `{ response, remember? }`, returns `boolean` | --- ### Messages | Method | Path | Description | Notes | | ------ | --------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/session/:id/message` | List messages in a session | query: `limit?`, returns `{ info: `Message`, parts: `Part[]`}[]` | | `POST` | `/session/:id/message` | Send a message and wait for response | body: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`, returns `{ info: `Message`, parts: `Part[]`}` | | `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `Message`, parts: `Part[]`}` | | `POST` | `/session/:id/prompt_async` | Send a message asynchronously (no wait) | body: same as `/session/:id/message`, returns `204 No Content` | | `POST` | `/session/:id/command` | Execute a slash command | body: `{ messageID?, agent?, model?, command, arguments }`, returns `{ info: `Message`, parts: `Part[]`}` | | `POST` | `/session/:id/shell` | Run a shell command | body: `{ agent, model?, command }`, returns `{ info: `Message`, parts: `Part[]`}` | --- ### Commands | Method | Path | Description | Response | | ------ | ---------- | ----------------- | --------------------------------------------- | | `GET` | `/command` | List all commands | Command[] | --- ### Files | Method | Path | Description | Response | | ------ | ------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------- | | `GET` | `/find?pattern=` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` | | `GET` | `/find/file?query=` | Find files and directories by name | `string[]` (paths) | | `GET` | `/find/symbol?query=` | Find workspace symbols | Symbol[] | | `GET` | `/file?path=` | List files and directories | FileNode[] | | `GET` | `/file/content?path=

` | Read a file | FileContent | | `GET` | `/file/status` | Get status for tracked files | File[] | #### `/find/file` query parameters - `query` (required): search string (fuzzy match) - `type` (optional): limit results to `"file"` or `"directory"` - `directory` (optional): override the project root for the search - `limit` (optional): max results (1–200) - `dirs` (optional): legacy flag (`"false"` returns only files) --- ### LSP, Formatters & MCP | Method | Path | Description | Response | | ------ | ------------ | -------------------------- | -------------------------------------------------------- | | `GET` | `/lsp` | Get LSP server status | LSPStatus[] | | `GET` | `/formatter` | Get formatter status | FormatterStatus[] | | `GET` | `/mcp` | Get MCP server status | `{ [name: string]: `MCPStatus` }` | | `POST` | `/mcp` | Add MCP server dynamically | body: `{ name, config }`, returns MCP status object | --- ### Agents | Method | Path | Description | Response | | ------ | -------- | ------------------------- | ------------------------------------------- | | `GET` | `/agent` | List all available agents | Agent[] | --- ### Logging | Method | Path | Description | Response | | ------ | ------ | ------------------------------------------------------------ | --------- | | `POST` | `/log` | Write log entry. Body: `{ service, level, message, extra? }` | `boolean` | --- ### Auth | Method | Path | Description | Response | | ------ | ----------- | ---------------------------------------------------- | --------- | | `PUT` | `/auth/:id` | Set authentication credentials for the given target. | `boolean` | --- ### Events | Method | Path | Description | Response | | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------- | | `GET` | `/event` | Server-sent events stream. First event is `server.connected`, then bus events | Server-sent events stream | --- ### Docs | Method | Path | Description | Response | | ------ | ------ | ------------------------- | --------------------------- | | `GET` | `/doc` | OpenAPI 3.1 specification | HTML page with OpenAPI spec | ============================================================================== # Dropstone SDK URL: https://docs.dropstone.io/cli/sdk Description: Type-safe JS client for the Dropstone agent runtime. SDK sessions inherit Dropstone's cross-surface memory (Continuity) — one persistent memory shared with the CLI, chat, and SDK. ============================================================================== The Dropstone JS/TS SDK provides a type-safe client for interacting with the **Dropstone agent runtime**. It spawns `dropstone serve` as a subprocess and gives you a typed HTTP client pointed at it. Because it runs the same local agent the CLI uses, every SDK session inherits your account memory — teach it once in the CLI, chat, or SDK and every surface already knows it (see [Memory (Continuity)](#memory-continuity)). For pure programmatic use (CI pipelines, automation, serverless), prefer the [HTTP API](./api) with a `DROPSTONE_API_KEY`. The SDK on this page is intended for embedding the interactive agent in a Node process where the CLI binary is installed alongside. See the [Server](./server) page for how the underlying HTTP API works. --- ## Install Install the SDK from npm: ```bash npm install @blankline/dropstone-sdk ``` --- ## Headless API client For CI pipelines, automation, and serverless you do not need the CLI at all. Use the headless client, which talks directly to the Dropstone HTTP API with an API key: ```typescript import { createDropstoneApi } from "@blankline/dropstone-sdk" // Reads DROPSTONE_API_KEY from the environment automatically. const dropstone = createDropstoneApi() const resp = await dropstone.chat.completions.create({ model: "dropstone-fast", // or "dropstone-pro" / "dropstone-heavy" messages: [{ role: "user", content: "Write a haiku about debugging." }], }) console.log(resp.choices[0].message.content) console.log("Cost: $" + resp.usage?.cost) // billed amount, in USD ``` ### Get an API key 1. Sign in at [dropstone.io/dashboard](https://dropstone.io/dashboard). 2. Open **Settings → API** at [dropstone.io/dashboard/settings](https://dropstone.io/dashboard/settings) and create a key — it looks like `dsk_live_<43 chars>`. 3. Set it as an environment variable (or pass `apiKey` to `createDropstoneApi`): ```bash export DROPSTONE_API_KEY=dsk_live_... ``` Treat your API key like a password. Never commit it to git or embed it in a frontend bundle. API-key requests are billed pay-per-use from your prepaid credit balance — plan allowances do not apply. See [Usage & limits](/getting-started/usage). Streaming works the same way, and the client is OpenAI-compatible — you can point the OpenAI SDK at Dropstone's base URL instead: ```typescript const stream = await dropstone.chat.completions.create({ model: "dropstone-fast", stream: true, messages: [{ role: "user", content: "Count to 5." }], }) for await (const chunk of stream) { process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "") } ``` See the [HTTP API](./api) page for the full reference. --- ## Create client Create an instance of dropstone: ```javascript import { createDropstone } from "@blankline/dropstone-sdk" const { client } = await createDropstone() ``` This starts both a server and a client. Every SDK method returns `{ data, request, response }`, so access the payload via `.data`. #### Options | Option | Type | Description | Default | | ---------- | ------------- | ------------------------------ | ----------- | | `hostname` | `string` | Server hostname | `127.0.0.1` | | `port` | `number` | Server port | `4096` | | `signal` | `AbortSignal` | Abort signal for cancellation | `undefined` | | `timeout` | `number` | Timeout in ms for server start | `5000` | | `config` | `Config` | Configuration object | `{}` | --- ## Config You can pass a configuration object to customize behavior. The instance still picks up your `dropstone.json`, but you can override or add configuration inline: ```javascript import { createDropstone } from "@blankline/dropstone-sdk" const dropstone = await createDropstone({ hostname: "127.0.0.1", port: 4096, config: { model: "dropstone/dropstone-pro", }, }) console.log(`Server running at ${dropstone.server.url}`) dropstone.server.close() ``` --- ## Memory (Continuity) Dropstone keeps one persistent memory per account. We call it **Continuity** — a cross-surface memory shared by the CLI, chat, VS Code, and the SDK. Teach it once anywhere and every surface already knows it. Sessions you run through the SDK use the same account memory as the CLI. What you teach the CLI is already known to SDK sessions, and what an SDK session records is available back in the CLI and chat. On every turn, the agent auto-recalls relevant memory before answering, so it does not re-learn what it already knows. The SDK agent can also read and write memory directly, with the same tools as the CLI: | Tool | Purpose | | --- | --- | | `memory_recall` | Recall the most relevant lessons for the current task | | `record_lesson` | Save a durable lesson (a rule or a fact) | | `list_lessons` | Show everything it has learned about you | | `forget_lesson` | Remove a lesson | Memory requires being signed in to Dropstone. The SDK server reads the same `auth.json` as the CLI, so sign in once with `dropstone` and SDK sessions inherit the same account memory. Nothing is stored if you are not signed in. #### Example State a preference from code and it is recorded the same way it would be in the CLI — visible in the CLI and chat afterwards: ```typescript const { client } = await createDropstone() const session = await client.session.create({ body: { title: "Teach memory" } }) await client.session.prompt({ path: { id: session.data.id }, body: { parts: [{ type: "text", text: "Remember this as a standing rule: always use bun, not npm." }], }, }) ``` #### Continuity vs `AGENTS.md` `AGENTS.md` is a project file you commit to Git for team conventions — stable, repo-scoped, and shared with anyone who clones it. Continuity is your private account memory: what you teach in the CLI, chat, or SDK follows your account across surfaces and projects. They solve different problems and work best together — project rules in `AGENTS.md`, personal cross-surface memory in Continuity. See [Rules](./rules) and [Memory](./memory). #### What gets remembered Memory stores only the rules and facts you explicitly teach it — preferences, conventions, and corrections that are worth carrying across sessions. It is distinct from the ephemeral context of a single session, which is not kept after the session ends. See the [Memory](./memory) page for how Dropstone decides what to keep. --- ## Client only If you already have a running instance of dropstone, you can create a client instance to connect to it: ```javascript import { createDropstoneClient } from "@blankline/dropstone-sdk" const client = createDropstoneClient({ baseUrl: "http://localhost:4096", }) ``` #### Options | Option | Type | Description | Default | | --------------- | ---------- | -------------------------------- | ----------------------- | | `baseUrl` | `string` | URL of the server | `http://localhost:4096` | | `fetch` | `function` | Custom fetch implementation | `globalThis.fetch` | | `parseAs` | `string` | Response parsing method | `auto` | | `responseStyle` | `string` | Return style: `data` or `fields` | `fields` | | `throwOnError` | `boolean` | Throw errors instead of return | `false` | --- ## Types The SDK includes TypeScript definitions for all API types. Import them directly: ```typescript import type { Session, Message, Part } from "@blankline/dropstone-sdk" ``` All types are generated from the server's OpenAPI specification, so the names you see in TypeScript map one-to-one to the [server](./server) request and response shapes. --- ## Errors The SDK can throw errors that you can catch and handle: ```typescript try { await client.session.get({ path: { id: "invalid-id" } }) } catch (error) { console.error("Failed to get session:", (error as Error).message) } ``` --- ## Structured Output You can request structured JSON output from the model by specifying an `format` with a JSON schema. The model will use a `StructuredOutput` tool to return validated JSON matching your schema. ### Basic Usage ```typescript const result = await client.session.prompt({ path: { id: sessionId }, body: { parts: [{ type: "text", text: "Research Dropstone and provide company info" }], format: { type: "json_schema", schema: { type: "object", properties: { company: { type: "string", description: "Company name" }, founded: { type: "number", description: "Year founded" }, products: { type: "array", items: { type: "string" }, description: "Main products", }, }, required: ["company", "founded"], }, }, }, }) // Access the structured output console.log(result.data.info.structured_output) // { company: "Dropstone", founded: 2024, products: ["Dropstone CLI"] } ``` ### Output Format Types | Type | Description | | ------------- | ------------------------------------------------------ | | `text` | Default. Standard text response (no structured output) | | `json_schema` | Returns validated JSON matching the provided schema | ### JSON Schema Format When using `type: 'json_schema'`, provide: | Field | Type | Description | | ------------ | --------------- | ---------------------------------------------------------- | | `type` | `'json_schema'` | Required. Specifies JSON schema mode | | `schema` | `object` | Required. JSON Schema object defining the output structure | | `retryCount` | `number` | Optional. Number of validation retries (default: 2) | ### Error Handling If the model fails to produce valid structured output after all retries, the response will include a `StructuredOutputError`: ```typescript if (result.data.info.error?.name === "StructuredOutputError") { console.error("Failed to produce structured output:", result.data.info.error.message) console.error("Attempts:", result.data.info.error.retries) } ``` ### Best Practices 1. **Provide clear descriptions** in your schema properties to help the model understand what data to extract 2. **Use `required`** to specify which fields must be present 3. **Keep schemas focused** - complex nested schemas may be harder for the model to fill correctly 4. **Set appropriate `retryCount`** - increase for complex schemas, decrease for simple ones --- ## APIs The SDK exposes all server APIs through a type-safe client. --- ### Global | Method | Description | Response | | ----------------- | ------------------------------- | ------------------------------------ | | `global.health()` | Check server health and version | `{ healthy: true, version: string }` | --- #### Examples ```javascript const health = await client.global.health() console.log(health.data.version) ``` --- ### App | Method | Description | Response | | -------------- | ------------------------- | ------------------------------------------- | | `app.log()` | Write a log entry | `boolean` | | `app.agents()` | List all available agents | Agent[] | --- #### Examples ```javascript // Write a log entry await client.app.log({ body: { service: "my-app", level: "info", message: "Operation completed", }, }) // List available agents const agents = await client.app.agents() ``` --- ### Project | Method | Description | Response | | ------------------- | ------------------- | --------------------------------------------- | | `project.list()` | List all projects | Project[] | | `project.current()` | Get current project | Project | --- #### Examples ```javascript // List all projects const projects = await client.project.list() // Get current project const currentProject = await client.project.current() ``` --- ### Path | Method | Description | Response | | ------------ | ---------------- | ---------------------------------------- | | `path.get()` | Get current path | Path | --- #### Examples ```javascript // Get current path information const pathInfo = await client.path.get() ``` --- ### Config | Method | Description | Response | | -------------- | --------------- | ------------------- | | `config.get()` | Get config info | Config | --- #### Examples ```javascript const config = await client.config.get() ``` --- ### Sessions | Method | Description | Notes | | ---------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `session.list()` | List sessions | Returns Session[] | | `session.get({ path })` | Get session | Returns Session | | `session.children({ path })` | List child sessions | Returns Session[] | | `session.create({ body })` | Create session | Returns Session | | `session.delete({ path })` | Delete session | Returns `boolean` | | `session.update({ path, body })` | Update session properties | Returns Session | | `session.init({ path, body })` | Analyze app and create `AGENTS.md` | Returns `boolean` | | `session.abort({ path })` | Abort a running session | Returns `boolean` | | `session.summarize({ path, body })` | Summarize session | Returns `boolean` | | `session.messages({ path })` | List messages in a session | Returns `{ info: `Message`, parts: `Part[]`}[]` | | `session.message({ path })` | Get message details | Returns `{ info: `Message`, parts: `Part[]`}` | | `session.prompt({ path, body })` | Send prompt message | `body.noReply: true` returns UserMessage (context only). Default returns AssistantMessage with AI response. Supports `body.outputFormat` for [structured output](#structured-output) | | `session.command({ path, body })` | Send command to session | Returns `{ info: `AssistantMessage`, parts: `Part[]`}` | | `session.shell({ path, body })` | Run a shell command | Returns AssistantMessage | | `session.revert({ path, body })` | Revert a message | Returns Session | | `session.unrevert({ path })` | Restore reverted messages | Returns Session | | `postSessionByIdPermissionsByPermissionId({ path, body })` | Respond to a permission request | Returns `boolean` | --- #### Examples ```javascript // Create and manage sessions const session = await client.session.create({ body: { title: "My session" }, }) const sessions = await client.session.list() // Send a prompt message const result = await client.session.prompt({ path: { id: session.data.id }, body: { model: { providerID: "dropstone", modelID: "dropstone-pro" }, parts: [{ type: "text", text: "Hello!" }], }, }) // Inject context without triggering AI response (useful for plugins) await client.session.prompt({ path: { id: session.data.id }, body: { noReply: true, parts: [{ type: "text", text: "You are a helpful assistant." }], }, }) ``` --- ### Files | Method | Description | Response | | ------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------- | | `find.text({ query })` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` | | `find.files({ query })` | Find files and directories by name | `string[]` (paths) | | `find.symbols({ query })` | Find workspace symbols | Symbol[] | | `file.read({ query })` | Read a file | `{ type: "raw" \| "patch", content: string }` | | `file.status({ query? })` | Get status for tracked files | File[] | `find.files` supports a few optional query fields: - `type`: `"file"` or `"directory"` - `directory`: override the project root for the search - `limit`: max results (1–200) --- #### Examples ```javascript // Search and read files const textResults = await client.find.text({ query: { pattern: "function.*dropstone" }, }) const files = await client.find.files({ query: { query: "*.ts", type: "file" }, }) const directories = await client.find.files({ query: { query: "packages", type: "directory", limit: 20 }, }) const content = await client.file.read({ query: { path: "src/index.ts" }, }) ``` --- ### Auth | Method | Description | Response | | ------------------- | ------------------------------ | --------- | | `auth.set({ ... })` | Set authentication credentials | `boolean` | --- #### Examples ```javascript await client.auth.set({ path: { id: "dropstone" }, body: { type: "api", key: "your-dropstone-api-key" }, }) ``` --- ### Events | Method | Description | Response | | ------------------- | ------------------------- | ------------------------- | | `event.subscribe()` | Server-sent events stream | Server-sent events stream | --- #### Examples ```javascript // Listen to real-time events const events = await client.event.subscribe() for await (const event of events.stream) { console.log("Event:", event.type, event.properties) } ``` --- ## v2 API The SDK ships a stable v1 surface (used in the examples above) and a v2 surface that mirrors the newer Effect HttpApi contract. Prefer v2 for new integrations: ```typescript import { createDropstone } from "@blankline/dropstone-sdk/v2" const { client, server } = await createDropstone() // v2 exposes a richer resource hierarchy: workspace, worktree, file, find, etc. const files = await client.file.list({ path: "src" }) ``` The v1 surface is kept for backward compatibility. New endpoints only land on v2. ============================================================================== # HTTP API URL: https://docs.dropstone.io/cli/api Description: Public HTTP API for programmatic access. OpenAI-compatible chat completions, pay-per-use credits, one key for Fast / Pro / Heavy. ============================================================================== The Dropstone HTTP API gives you programmatic access to the same three models the CLI uses — **Dropstone Fast**, **Pro**, and **Heavy** — over an OpenAI-compatible interface. One key, one bill, three model families. Use the API when you want to call Dropstone from your own code: CI pipelines, internal tools, automation, or third-party apps. For interactive coding, use the [CLI](./cli) instead. The public API is in preview. The endpoint shape is stable but pricing and rate limits may change before GA. Pin the surface you depend on. --- ## Base URL ``` https://api.dropstone.io/api/v1 ``` All endpoints are mounted under `/api/v1`. The path is versioned so future breaking changes will land under `/api/v2` without disrupting your code. --- ## Authentication Every request must include an API key in the `Authorization` header: ```http Authorization: Bearer dsk_live_ ``` ### Generate a key 1. Sign in to [dropstone.io/dashboard](https://dropstone.io/dashboard) 2. Open **Settings → API** 3. Click **Create key**, give it a name (e.g. `Production CI`) 4. Copy the full key — **you will only see it once** Keys look like `dsk_live_<43 chars>`. Store them in a secrets manager or in the `DROPSTONE_API_KEY` environment variable. ### Revoking a key Revoke from the same Settings → API page. Revocation is immediate; in-flight requests with the key continue, new requests get `401`. Treat your API key like a password. Never commit it to git, never paste it in chat or screenshots, never embed it in a frontend bundle. If a key leaks, revoke it immediately and create a new one. --- ## Credits & billing The API is **pay-per-use against a credit balance**. There is no free tier and no subscription on the API surface. - Buy credits at [dropstone.io/dashboard/billing](https://dropstone.io/dashboard/billing). Stripe handles checkout. - Each request deducts its cost from your `creditBalance`. - When `creditBalance` drops to **$0**, the API returns [`402 Insufficient credits`](#error-codes) until you top up. - Subscription credits (Pro/Teams monthly allowance) and free-request quotas **do not apply** to API key requests. ### Pricing Pricing is real inference cost passed through with a **30% markup** (`1.3x`). The full per-request cost is returned in the response `usage.cost` field, so you can verify every charge. | Tier | Approx $/M input | Approx $/M output | |---|---|---| | `dropstone-fast` | $0.35 | $1.43 | | `dropstone-pro` | $0.72 | $2.86 | | `dropstone-heavy` | $0.78 | $3.25 | Cached prompt tokens are billed at the provider's cached rate (typically ~5–10% of the normal input rate), so multi-turn conversations get progressively cheaper. --- ## Models ### `GET /api/v1/models` List the three available tiers. ```bash curl https://api.dropstone.io/api/v1/models \ -H "Authorization: Bearer $DROPSTONE_API_KEY" ``` ```python import os, httpx r = httpx.get( "https://api.dropstone.io/api/v1/models", headers={"Authorization": f"Bearer {os.environ['DROPSTONE_API_KEY']}"}, ) print(r.json()) ``` ```javascript const res = await fetch("https://api.dropstone.io/api/v1/models", { headers: { Authorization: `Bearer ${process.env.DROPSTONE_API_KEY}` }, }) console.log(await res.json()) ``` Response: ```json { "object": "list", "data": [ { "id": "dropstone-fast", "object": "model", "display_name": "Dropstone Fast", "owned_by": "dropstone" }, { "id": "dropstone-pro", "object": "model", "display_name": "Dropstone Pro", "owned_by": "dropstone" }, { "id": "dropstone-heavy", "object": "model", "display_name": "Dropstone Heavy", "owned_by": "dropstone" } ] } ``` --- ## Chat completions ### `POST /api/v1/chat/completions` OpenAI-compatible chat completions. If you have used any OpenAI-compatible API, this looks identical. #### Request body | Field | Type | Required | Description | |---|---|---| | `model` | `string` | yes | One of `dropstone-fast`, `dropstone-pro`, `dropstone-heavy` | | `messages` | `array` | yes | List of message objects with `role` and `content` | | `stream` | `boolean` | no | When `true`, returns Server-Sent Events. Default `false` | | `temperature` | `number` | no | Sampling temperature, `0..2`. Default model-specific | | `max_tokens` | `number` | no | Cap on output tokens | | `tools` | `array` | no | Function-calling tool schemas, OpenAI format | | `tool_choice` | `string \| object` | no | `"auto"`, `"none"`, or a specific tool | #### Example: simple chat ```bash curl https://api.dropstone.io/api/v1/chat/completions \ -H "Authorization: Bearer $DROPSTONE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "dropstone-fast", "messages": [ {"role": "user", "content": "Write a haiku about debugging."} ] }' ``` ```python import os, httpx r = httpx.post( "https://api.dropstone.io/api/v1/chat/completions", headers={ "Authorization": f"Bearer {os.environ['DROPSTONE_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "dropstone-fast", "messages": [{"role": "user", "content": "Write a haiku about debugging."}], }, timeout=60, ) print(r.json()["choices"][0]["message"]["content"]) ``` ```javascript const res = await fetch("https://api.dropstone.io/api/v1/chat/completions", { method: "POST", headers: { Authorization: `Bearer ${process.env.DROPSTONE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "dropstone-fast", messages: [{ role: "user", content: "Write a haiku about debugging." }], }), }) const data = await res.json() console.log(data.choices[0].message.content) ``` #### Response ```json { "id": "gen-1779530142-EfBhlhO1U2frV6tvMgKV", "object": "chat.completion", "created": 1779530142, "model": "dropstone-fast", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Stack trace at midnight..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 11, "completion_tokens": 23, "total_tokens": 34, "cost": 0.0000098 } } ``` The `usage.cost` field is the **billed amount in USD** — what was deducted from your credit balance for this request (real provider cost × 1.3 markup). --- ## Streaming Set `"stream": true` to get a Server-Sent Events stream of token chunks. The stream ends with a `data: [DONE]` line and a final chunk containing the full `usage` block. ```bash curl https://api.dropstone.io/api/v1/chat/completions \ -H "Authorization: Bearer $DROPSTONE_API_KEY" \ -H "Content-Type: application/json" \ -N \ -d '{ "model": "dropstone-fast", "stream": true, "messages": [{"role": "user", "content": "Count to 5."}] }' ``` ```python import os, httpx with httpx.stream( "POST", "https://api.dropstone.io/api/v1/chat/completions", headers={"Authorization": f"Bearer {os.environ['DROPSTONE_API_KEY']}"}, json={ "model": "dropstone-fast", "stream": True, "messages": [{"role": "user", "content": "Count to 5."}], }, timeout=60, ) as r: for line in r.iter_lines(): if line.startswith("data: "): print(line[6:]) ``` ```javascript const res = await fetch("https://api.dropstone.io/api/v1/chat/completions", { method: "POST", headers: { Authorization: `Bearer ${process.env.DROPSTONE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "dropstone-fast", stream: true, messages: [{ role: "user", content: "Count to 5." }], }), }) const reader = res.body.getReader() const decoder = new TextDecoder() while (true) { const { value, done } = await reader.read() if (done) break process.stdout.write(decoder.decode(value)) } ``` --- ## OpenAI SDK compatibility Because the surface is OpenAI-compatible, you can use the official OpenAI SDK by overriding `base_url`: ```python from openai import OpenAI client = OpenAI( base_url="https://api.dropstone.io/api/v1", api_key=os.environ["DROPSTONE_API_KEY"], ) resp = client.chat.completions.create( model="dropstone-fast", messages=[{"role": "user", "content": "Hello"}], ) print(resp.choices[0].message.content) ``` ```javascript import OpenAI from "openai" const client = new OpenAI({ baseURL: "https://api.dropstone.io/api/v1", apiKey: process.env.DROPSTONE_API_KEY, }) const resp = await client.chat.completions.create({ model: "dropstone-fast", messages: [{ role: "user", content: "Hello" }], }) console.log(resp.choices[0].message.content) ``` --- ## Error codes | Code | Meaning | Action | |---|---|---| | `400` | Invalid request body (bad `model`, missing `messages`, etc.) | Check the response `error.message` | | `401` | Missing, malformed, or revoked API key | Generate a new key in the dashboard | | `402` | **Insufficient credits.** Balance is `$0` or negative | [Top up at /dashboard/billing](https://dropstone.io/dashboard/billing) | | `403` | Account suspended or banned | Contact support | | `429` | Rate limit (future — not enforced today) | Back off and retry | | `500` | Server error | Retry with exponential backoff | | `502` | Upstream provider error | Retry with exponential backoff | ### 402 response shape ```json { "error": "Insufficient credits", "balance": 0, "message": "Your credit balance is empty. Top up at https://dropstone.io/dashboard/billing to continue.", "topUpUrl": "https://dropstone.io/dashboard/billing" } ``` --- ## Rate limits There are no hard rate limits enforced on the API today. Per-key usage tiers and daily spend caps are planned — when they ship, your existing keys will be auto-tiered based on lifetime spend, similar to OpenAI's tier system. For now, set per-key budgets yourself by tracking the `usage.cost` field in your application. --- ## Recommended practices - **Use environment variables**, never inline keys: `DROPSTONE_API_KEY=dsk_live_...`. - **One key per service**, not one key shared everywhere. Easier to revoke when a service is compromised. - **Watch `usage.cost`** in responses to track spend in real time. - **Handle 402 gracefully** — your app should detect it and surface a top-up CTA rather than retrying. - **Cache responses** for repeated identical requests on your side — we cache at the model level, but you save the full markup by short-circuiting before reaching us. --- ## Differences from the CLI and SDK | Surface | Auth | Pricing model | Models | Use case | |---|---|---|---| | **HTTP API** (this page) | API key | Pay-per-use from credit balance | Fast / Pro / Heavy | CI, automation, integrations | | **CLI** ([docs](./cli)) | Interactive sign-in | Subscription + credit balance | Same three + free open-source models | Day-to-day coding in a terminal | | **JS SDK** ([docs](./sdk)) | Spawns local CLI, inherits its auth | Same as CLI | Same as CLI | Embedding the agent in a Node app | If you want headless programmatic access in CI or a server, the **HTTP API is the right surface**. The SDK is for embedding the interactive agent in a Node process where a human is still in the loop. --- ## Coming soon These are on the roadmap and will land under the same `/api/v1` namespace: - **`POST /api/v1/agent/run`** — agent loop endpoint. Send a task, get a finished diff. Server-side multi-turn loop with built-in tools (file editing, web search, code execution). Flat per-task pricing. - **`POST /api/v1/memory/store`** + **`GET /api/v1/memory/query`** — stateful memory via Qdrant. Agent context that persists across calls. - **MCP tool injection** — include your own MCP server URLs in agent requests, agent calls them as native tools. - **Per-key spend caps** — set a daily $ limit per key from the dashboard. CI safety net. Star [the GitHub repo](https://github.com/blankline-org/dropstone-cli) or watch the [changelog](../getting-started/changelog) to know when they ship. ============================================================================== # Network URL: https://docs.dropstone.io/cli/network Description: Configure proxies and custom certificates. ============================================================================== Dropstone supports standard proxy environment variables and custom certificates for enterprise network environments. --- ## Proxy Dropstone respects standard proxy environment variables. ```bash # HTTPS proxy (recommended) export HTTPS_PROXY=https://proxy.example.com:8080 # HTTP proxy (if HTTPS not available) export HTTP_PROXY=http://proxy.example.com:8080 # Bypass proxy for local server (required) export NO_PROXY=localhost,127.0.0.1 ``` Dropstone uses a local HTTP loopback during interactive sessions. You must bypass the proxy for `localhost`/`127.0.0.1` to prevent routing loops. You can configure the local bind address using [CLI flags](./cli#run). --- ### Authenticate If your proxy requires basic authentication, include credentials in the URL. ```bash export HTTPS_PROXY=http://username:password@proxy.example.com:8080 ``` Avoid hardcoding passwords in shell config. Use environment variables, your OS keyring, or a secrets manager. For proxies that require advanced authentication (NTLM, Kerberos), front Dropstone with a local authenticating proxy (such as [cntlm](https://github.com/Evengard/cntlm)) and point `HTTPS_PROXY` at the local proxy instead. --- ## Custom certificates If your enterprise uses custom CAs for HTTPS connections, configure Dropstone to trust them. ```bash export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem ``` This works for both proxy connections and direct API access. ============================================================================== # Windows (WSL) URL: https://docs.dropstone.io/cli/windows-wsl Description: Run Dropstone on Windows using WSL for the best experience. ============================================================================== While Dropstone can run directly on Windows, we recommend using [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) for the best experience. WSL provides a Linux environment that works seamlessly with Dropstone's features. WSL offers better file system performance, full terminal support, and compatibility with development tools that Dropstone relies on. --- ## Setup 1. **Install WSL** If you haven't already, [install WSL](https://learn.microsoft.com/en-us/windows/wsl/install) using the official Microsoft guide. 2. **Install Dropstone in WSL** Once WSL is set up, open your WSL terminal and install Dropstone using the install script: ```bash curl -fsSL https://dropstone.io/install | bash ``` 3. **Use Dropstone from WSL** Navigate to your project directory (access Windows files via `/mnt/c/`, `/mnt/d/`, etc.) and run Dropstone. ```bash cd /mnt/c/Users/YourName/project dropstone ``` --- ## Web Client + WSL For the best web experience on Windows: 1. **Run `dropstone web` in the WSL terminal** rather than PowerShell: ```bash dropstone web --hostname 0.0.0.0 ``` 2. **Access from your Windows browser** at `http://localhost:` (Dropstone prints the URL) Running `dropstone web` from WSL ensures proper file system access and terminal integration while still being accessible from your Windows browser. --- ## Accessing Windows Files WSL can access all your Windows files through the `/mnt/` directory: - `C:` drive → `/mnt/c/` - `D:` drive → `/mnt/d/` - And so on... Example: ```bash cd /mnt/c/Users/YourName/Documents/project dropstone ``` For the smoothest experience, clone or copy your repo into the WSL filesystem (for example under `~/code/`) and run Dropstone there. WSL's native filesystem is much faster than `/mnt/c/` for large projects. --- ## Tips - Keep Dropstone running in WSL for projects stored on Windows drives - file access is seamless - Use VS Code's [WSL extension](https://code.visualstudio.com/docs/remote/wsl) alongside Dropstone for an integrated development workflow - Your Dropstone config and sessions are stored within the WSL environment at `~/.local/share/dropstone/` ============================================================================== # Enterprise URL: https://docs.dropstone.io/cli/enterprise Description: Using Dropstone securely in your organization. ============================================================================== Dropstone Enterprise is for organizations that want centralized config, SSO, and admin controls across their developers. Dropstone does not store your code or context data. See [Data handling](#data-handling) below for the full posture. To get started with Dropstone Enterprise: 1. Run an internal trial with your team using the standard plan. 2. **Contact us** to discuss pricing and implementation. --- ## Trial Your developers can install Dropstone today and start using it. See the [Quickstart](../getting-started/quick-start) for the install flow. A trial does not require an enterprise contract, and nothing in the default configuration sends code to anyone outside the team. --- ### Data handling **Your prompts, code, and conversation transcripts are never used to train models and are not retained beyond the lifetime of your session.** Dropstone uses session-scoped prompt caching to reduce cost and latency, the same way Anthropic and OpenAI do: cached content is isolated to your own account, expires automatically, and is never reused for any other user or sent to model training. These controls are enforced and reviewed by Blankline, Dropstone's parent company. Blankline's compliance team audits Dropstone's data handling on a recurring basis and retains revocation authority over the production access of any individual or system that breaches the policy. See the [Trust page](https://dropstone.io/trust) for the full posture, including subprocessor disclosures and the runtime security boundary. --- ### Code ownership **You own all code produced by Dropstone.** There are no licensing restrictions or ownership claims. --- ## Pricing Dropstone Enterprise uses a per-seat model with a flat monthly cost per developer. For details and a custom quote based on your organization's needs, **contact us**. --- ## Deployment Once you have completed your trial and are ready to roll Dropstone out across your organization, **contact us** to set up the enterprise contract and the central config. --- ### Central config Dropstone Enterprise organizations get a single central config that is served to every developer's CLI on sign-in. The config can pin: - Default model tier and reasoning effort - Permissions (which tools an agent can run without approval) - Allowed MCP servers - Audit and telemetry destinations Users cannot override managed values locally. See [Managed settings](./config#managed-settings) for the underlying mechanism (also available outside enterprise contracts for self-managed deployments). --- ### SSO integration Dropstone Enterprise integrates with SAML and OIDC identity providers (Okta, Azure AD, Google Workspace, and any standards-compliant IdP). Developers sign in through your existing identity system; revoking access in your IdP immediately revokes Dropstone access for that user. --- ## FAQ

What is Dropstone Enterprise? Dropstone Enterprise is a per-seat plan that adds SSO sign-in, a central config that admins control, an enterprise data-handling guarantee (no retention, no training, audited by Blankline), and a named point of contact for support.
How do I get started? Run a trial internally first. Dropstone does not store your code or context data by default, so you don't need an enterprise contract to evaluate it. When you are ready to roll it out across the team, **contact us**.
How does enterprise pricing work? Per-seat. For a custom quote based on team size and feature requirements, **contact us**.
Is my data secure with Dropstone Enterprise? Yes. Dropstone does not retain your code, prompts, or conversation transcripts beyond the in-flight inference call, and never uses them to train models. Session-scoped prompt caching is isolated per account and expires automatically. These controls are reviewed by Blankline's compliance team on a recurring basis. See the [Trust page](https://dropstone.io/trust) for the full posture.
Can we use our own private NPM registry? Yes. Dropstone supports private npm registries through standard `.npmrc` file support. If your organization uses a private registry (JFrog Artifactory, Nexus, GitHub Packages, or similar), authenticate developers before running Dropstone. To set up authentication with your private registry: ```bash npm login --registry=https://your-company.jfrog.io/api/npm/npm-virtual/ ``` This creates `~/.npmrc` with authentication details. Dropstone picks it up automatically. Developers must be logged into the private registry before running Dropstone, otherwise package installs from npm-based plugins will fail. Alternatively, configure `~/.npmrc` manually: ```bash title="~/.npmrc" registry=https://your-company.jfrog.io/api/npm/npm-virtual/ //your-company.jfrog.io/api/npm/npm-virtual/:_authToken=${NPM_AUTH_TOKEN} ```
============================================================================== # Troubleshooting URL: https://docs.dropstone.io/cli/troubleshooting Description: Common issues and how to resolve them. ============================================================================== To debug issues with Dropstone, start by checking the logs and local data it stores on disk. --- ## Logs Log files are written to: - **macOS / Linux**: `~/.local/share/dropstone/log/` - **Windows**: press `WIN+R` and paste `%USERPROFILE%\.local\share\dropstone\log` Log files are named with timestamps (for example `2026-05-23T123456.log`) and the most recent 10 log files are kept. You can set the log level with the `--log-level` command-line option for more detailed debug output: ```bash dropstone --log-level DEBUG ``` `--print-logs` also streams logs to stderr in real time: ```bash dropstone --print-logs ``` --- ## Storage Dropstone stores session data and other application data on disk at: - **macOS / Linux**: `~/.local/share/dropstone/` - **Windows**: press `WIN+R` and paste `%USERPROFILE%\.local\share\dropstone` This directory contains: - `auth.json`: Authentication credentials - `log/`: Application logs - `project/`: Project-specific data like session history - If the project is inside a Git repo, it is stored in `.//storage/` - Otherwise it is stored in `./global/storage/` --- ## Common issues ### Dropstone won't start 1. Check the logs for an error message. 2. Try running with `--print-logs` to stream logs to stderr. 3. Ensure you are on the latest version: `dropstone update`. --- ### Authentication issues If sign-in or token validation fails: 1. Re-run `dropstone` and sign in again through the browser flow. 2. If you are in a headless environment, set `DROPSTONE_API_KEY` from a token issued at [dropstone.io/account](https://dropstone.io/account). 3. Confirm your network allows outbound HTTPS to `dropstone.io`. If you are behind a corporate proxy, see [Network](./network). --- ### Model not found If you see `ModelNotFoundError`, you are likely referencing a model ID that doesn't exist. Use one of: - `dropstone/dropstone-fast` - `dropstone/dropstone-pro` - `dropstone/dropstone-heavy` Run `dropstone models` to confirm what's available to your account. --- ### Initialisation error If you see an `InitError` on launch, your stored credentials may be invalid or corrupted. 1. Clear your stored data: ```bash rm -rf ~/.local/share/dropstone ``` On Windows: press `WIN+R` and delete `%USERPROFILE%\.local\share\dropstone`. 2. Re-run `dropstone` and sign in again. --- ### API call errors If you see API call errors during a session, the on-disk cache may be stale. 1. Clear the cache: ```bash rm -rf ~/.cache/dropstone ``` On Windows: press `WIN+R` and delete `%USERPROFILE%\.cache\dropstone`. 2. Restart Dropstone. --- ### Copy / paste not working on Linux Linux users need one of the following clipboard utilities installed for copy/paste to work: **X11** ```bash apt install -y xclip # or apt install -y xsel ``` **Wayland** ```bash apt install -y wl-clipboard ``` **Headless** ```bash apt install -y xvfb # then Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 & export DISPLAY=:99.0 ``` Dropstone prefers `wl-clipboard` on Wayland and falls back to `xclip` then `xsel` on X11. --- ### Windows: General performance issues If you are seeing slow performance, file-access problems, or terminal glitches on native Windows, switch to [WSL](./windows-wsl). WSL gives you a Linux environment that runs Dropstone with native filesystem speed and full terminal support. --- ## Getting help - Check the [Common issues](#common-issues) section above - Read the relevant page in the [CLI reference](./cli) or [Configuration](./config) - For bug reports, feature requests, or enterprise inquiries, [contact us](https://dropstone.io/contact) ============================================================================== # Common issues URL: https://docs.dropstone.io/troubleshooting/common_issues Description: Fix common Dropstone CLI install and runtime issues. Step-by-step solutions for failed installs, auth problems, and update errors. ============================================================================== The most common issues Dropstone users hit, with the steps to fix them. For runtime errors and per-feature debugging, see the [CLI troubleshooting](../cli/troubleshooting) page. ## Install fails on macOS ### "Command not found: brew" You need Homebrew first. Install it once: ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` On Apple Silicon, also add Homebrew to your PATH: ```bash echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)" ``` Then re-run the Dropstone install: ```bash brew tap blankline-org/dropstone-cli brew install dropstone ``` ### "Cannot install: package already exists" Force-overwrite the existing install: ```bash brew uninstall dropstone brew install dropstone ``` ### Homebrew tap fails to refresh Clear the cache and re-tap: ```bash brew untap blankline-org/dropstone-cli brew cleanup brew tap blankline-org/dropstone-cli brew install dropstone ``` ## Install fails on Windows ### "irm is not recognized as an internal or external command" You're in CMD, not PowerShell. Either switch to PowerShell: ```powershell irm https://dropstone.io/install.ps1 | iex ``` Or use the CMD installer: ```bash curl -fsSL https://dropstone.io/install.cmd -o install.cmd && install.cmd ``` ### "The token '&&' is not a valid statement separator" You're in PowerShell trying to run the CMD command. Switch to the PowerShell one above. ### Pending update did not apply If `dropstone update` reported success but `dropstone --version` still shows the old version, restart your terminal. On Windows the new binary swaps in on next launch. If that still doesn't help, force-reinstall: ```powershell irm https://dropstone.io/install.ps1 | iex ``` ## Authentication ### "Failed to sign in" 1. Run `dropstone` again. On first launch it opens [dropstone.io/login](https://dropstone.io/login) for PKCE-based sign-in. 2. If the browser flow fails, paste a token instead. Grab one at [dropstone.io/account](https://dropstone.io/account) and choose "Paste a token" at the sign-in prompt. ### "Session expired" Run `/login` from inside Dropstone to refresh your credentials. ### Stuck on the wrong account To switch accounts, run `/login` from inside Dropstone and pick the right account at the browser prompt. ## Update problems ### `dropstone update` reports "Update Available" but does nothing This usually means the auto-installer doesn't have write access to the binary's directory. Reinstall using your original method: | Platform | Command | | -------- | ------- | | macOS (Homebrew) | `brew upgrade dropstone` | | macOS / Linux (script) | `curl -fsSL https://dropstone.io/install \| bash` | | Windows (PowerShell) | `irm https://dropstone.io/install.ps1 \| iex` | ### Stuck on an old version Check what's installed: ```bash dropstone --version ``` Compare against the latest at [download.dropstone.io/latest.txt](https://download.dropstone.io/latest.txt). If they don't match, reinstall using the platform command above. ## Still having issues? If none of the above resolved your problem, see the more detailed [CLI troubleshooting](../cli/troubleshooting) page, or open an issue at [dropstone.io/contact](https://dropstone.io/contact) with: - Your OS and version - The output of `dropstone --version` - The full error message and the exact command you ran ============================================================================== # Dropstone Troubleshooting Guide - Diagnose & Fix Issues URL: https://docs.dropstone.io/troubleshooting/troubleshooting_guide Description: Comprehensive troubleshooting for Dropstone Desktop. Diagnose authentication, connectivity, performance, and agent issues. Find log files, reset settings, and get support. ============================================================================== This guide provides systematic approaches to diagnosing and resolving common issues with Dropstone.io. Follow these steps to gather the necessary information before reaching out to support. ## Essential Information for Troubleshooting The following information is critical for most troubleshooting scenarios within Dropstone: ### 1. Visual Documentation **Screenshot of Issue** (redact any sensitive information) - Capture the entire application window showing the error - Include any error messages or dialogs - Ensure timestamps are visible if available ### 2. Reproduction Steps Provide detailed steps to reproduce the issue: ``` 1. Action taken (e.g., "Clicked on 'Deploy' button") 2. Expected behavior 3. Actual behavior 4. Frequency (always, sometimes, once) ``` ### 3. System Information Retrieve system information from: **Dropstone** → **Help** → **About** This includes: - Dropstone version - Operating system - Architecture (x64, arm64) - Electron version - Node.js version ### 4. Network Configuration Are you using any of the following? - VPN (Virtual Private Network) - Zscaler or other security proxies - Corporate firewall - Custom DNS settings ### 5. Developer Tools Console Access developer tools to check for JavaScript errors: **Dropstone** → **Help** → **Toggle Developer Tools** Navigate to the **Console** tab and check for: - Red error messages - Warning messages related to your issue - Network request failures Copy any relevant error stack traces. ### 6. Application Logs #### Windows Logs are located at: ``` C:\Users\\AppData\Roaming\Dropstone\logs ``` Access via Command Palette: 1. Press `Ctrl` + `Shift` + `P` 2. Type and select: **Developer: Open Logs Folder** #### macOS Logs are located at: ``` ~/Library/Application Support/Dropstone/logs ``` Access via Command Palette: 1. Press `Cmd` + `Shift` + `P` 2. Type and select: **Developer: Open Logs Folder** #### Linux Logs are located at: ``` ~/.config/Dropstone/logs ``` #### Viewing Logs in Application Navigate to: **Dropstone** → **Terminal** → **Output** Select from the dropdown: - **Window** - General application logs - **Dropstone Core** - Core functionality logs - **Dropstone Deployment** - Deployment-related logs - **Dropstone Storage** - Storage and database logs - **Dropstone API** - API request/response logs --- ## Common Issues and Solutions ### Connection Issues #### Problem: Unable to Connect to Dropstone Services **Symptoms:** - "Connection timeout" errors - "Unable to reach server" messages - Indefinite loading states **Solutions:** 1. **Check Internet Connection** ```bash # Windows ping dropstone.io # macOS/Linux ping dropstone.io ``` 2. **Verify Firewall Settings** - Ensure Dropstone is allowed through your firewall - Check corporate network policies - Whitelist `*.dropstone.io` domain 3. **Proxy Configuration** Configure proxy settings: **Dropstone** → **Settings** → **Network** → **Proxy Settings** Or set environment variables: ```bash export HTTP_PROXY=http://proxy.example.com:8080 export HTTPS_PROXY=http://proxy.example.com:8080 ``` 4. **DNS Resolution** - Flush DNS cache - Try alternative DNS (8.8.8.8, 1.1.1.1) ### Authentication Issues #### Problem: Login Failures or Token Expiration **Symptoms:** - "Authentication failed" errors - Repeated login prompts - 401 Unauthorized responses **Solutions:** 1. **Clear Authentication Cache** **Dropstone** → **Command Palette** → **Clear Authentication Cache** 2. **Re-authenticate** ``` 1. Sign out from Dropstone 2. Clear browser cookies for dropstone.io 3. Sign in again ``` 3. **Check Token Validity** Navigate to: **Settings** → **Account** → **Session Management** Review active sessions and revoke suspicious ones. 4. **SSO Issues** If using Single Sign-On: - Verify SSO provider is accessible - Check for expired SAML assertions - Contact your identity provider administrator ### Performance Issues #### Problem: Slow Application Response or High CPU Usage **Symptoms:** - Lag when typing or clicking - High CPU/memory usage - Frozen or unresponsive UI **Solutions:** 1. **Check Resource Usage** **Dropstone** → **Help** → **Process Manager** Identify processes consuming excessive resources. 2. **Disable Extensions** Temporarily disable extensions to isolate the issue: **Settings** → **Extensions** → Disable all → Restart 3. **Clear Cache** ``` Dropstone → Settings → Advanced → Clear Cache ``` 4. **Reduce Project Size** - Exclude large files from indexing - Add to `.dpsignore` file: ``` node_modules/ dist/ build/ *.log .git/ ``` 5. **Hardware Acceleration** Toggle GPU acceleration: **Settings** → **System** → **Use Hardware Acceleration** ### Deployment Issues #### Problem: Failed Deployments **Symptoms:** - Build failures - Deployment timeouts - "Unable to push to remote" errors **Solutions:** 1. **Check Build Logs** View detailed build output: **Deployment** → **History** → Select failed deployment → **View Logs** 2. **Verify Environment Variables** ``` Settings → Deployment → Environment Variables ``` Ensure all required variables are set. 3. **Check Deployment Configuration** Validate your `dropstone.config.js`: ```javascript module.exports = { build: { command: 'npm run build', output: 'dist' }, deployment: { region: 'us-east-1', runtime: 'nodejs18.x' } } ``` 4. **Storage Quota** Verify you haven't exceeded storage limits: **Dashboard** → **Usage** → **Storage** 5. **Build Timeout** Increase timeout in configuration: ```javascript deployment: { timeout: 900 // 15 minutes in seconds } ``` ### Storage and Database Issues #### Problem: Data Sync or Storage Errors **Symptoms:** - "Storage quota exceeded" - Sync conflicts - Data not persisting **Solutions:** 1. **Check Storage Usage** **Dashboard** → **Storage** → **Usage Statistics** 2. **Resolve Sync Conflicts** ``` 1. Navigate to conflicted file 2. Dropstone will show conflict markers 3. Resolve manually or select version to keep ``` 3. **Database Connection** Test database connectivity: ```javascript // In Dropstone console await dropstone.db.test() ``` 4. **Clear Local Cache** ``` Settings → Storage → Clear Local Cache ``` Warning: This will remove locally cached data. 5. **Backup and Restore** Create backup before troubleshooting: ``` Dropstone → Tools → Backup → Create Backup ``` --- ## Advanced Troubleshooting ### Safe Mode Start Dropstone in safe mode to disable all extensions: **Windows/Linux:** ```bash dropstone --disable-extensions ``` **macOS:** ```bash /Applications/Dropstone.app/Contents/MacOS/Dropstone --disable-extensions ``` ### Reset to Default Settings To reset all settings to defaults: 1. **Backup Current Settings** ``` Settings → Advanced → Export Settings ``` 2. **Reset** ``` Settings → Advanced → Reset All Settings ``` ### Verbose Logging Enable detailed logging for debugging: 1. Open Command Palette (`Ctrl/Cmd` + `Shift` + `P`) 2. Select: **Developer: Set Log Level** 3. Choose: **Trace** Logs will now include detailed diagnostic information. ### Network Diagnostics Run built-in network diagnostics: ``` Dropstone → Help → Run Network Diagnostics ``` This checks: - DNS resolution - API endpoint accessibility - WebSocket connections - CDN availability --- ## Getting Help ### Before Contacting Support Ensure you have: - [ ] Checked this troubleshooting guide - [ ] Reviewed the [Status Page](https://status.dropstone.io) - [ ] Gathered all essential troubleshooting information ### Contact Support **Email:** support@blankline.org **Include in your message:** 1. Issue summary 2. Steps to reproduce 3. System information 4. Relevant logs (last 100 lines) 5. Screenshots 6. What you've already tried ### Other Resources - **Documentation:** [docs.dropstone.io](https://docs.dropstone.io) - **Status Page:** [status.dropstone.io](https://status.dropstone.io) - **Sales / Enterprise:** [dropstone.io/contact](https://www.dropstone.io/contact) --- ## Useful Commands ### Command Palette Quick Reference | Command | Description | |---------|-------------| | `Ctrl/Cmd` + `Shift` + `P` | Open Command Palette | | `Ctrl/Cmd` + `,` | Open Settings | | `Ctrl/Cmd` + `Shift` + `D` | Open Developer Tools | | `Ctrl/Cmd` + `Shift` + `L` | Open Logs | | `Ctrl/Cmd` + `Shift` + `R` | Reload Window | | `Ctrl/Cmd` + `K` `Ctrl/Cmd` + `T` | Clear Terminal | ### CLI Diagnostics ```bash # Check Dropstone CLI version dropstone --version # Verify installation dropstone doctor # Test API connectivity dropstone ping # View current configuration dropstone config list # Clear local cache dropstone cache clear # Export logs dropstone logs export --output ./dropstone-logs.txt ``` --- ## Appendix ### Log File Locations | Platform | Location | |----------|----------| | Windows | `%APPDATA%\Dropstone\logs` | | macOS | `~/Library/Application Support/Dropstone/logs` | | Linux | `~/.config/Dropstone/logs` | ### Configuration File Locations | Platform | Location | |----------|----------| | Windows | `%APPDATA%\Dropstone\config.json` | | macOS | `~/Library/Application Support/Dropstone/config.json` | | Linux | `~/.config/Dropstone/config.json` | ### Environment Variables | Variable | Purpose | Example | |----------|---------|---------| | `DROPSTONE_API_URL` | Override API endpoint | `https://api.dropstone.io` | | `DROPSTONE_LOG_LEVEL` | Set logging verbosity | `debug`, `info`, `warn`, `error` | | `DROPSTONE_TIMEOUT` | API request timeout (ms) | `30000` | | `DROPSTONE_PROXY` | Proxy server URL | `http://proxy:8080` | | `DROPSTONE_DISABLE_TELEMETRY` | Disable telemetry | `true`, `false` | --- *Last Updated: September 29, 2025* *Version: 1.0.0* ============================================================================== # Installation Guide URL: https://docs.dropstone.io/troubleshooting/downloads Description: Download, install, and configure Dropstone on Windows and Apple Silicon macOS. ============================================================================== ## Overview Dropstone is an **AI-powered platform** for code analysis, debugging & automation. This guide will walk you through downloading, installing, and configuring Dropstone on **Windows** and **Apple Silicon macOS**. --- ## Download Dropstone ### System Requirements | Component | Windows (Minimum / Recommended) | macOS Silicon (Minimum / Recommended) | |-----------|--------------------------------|--------------------------------------| | **OS** | Windows 10 / Latest Windows 11 | macOS 12 Monterey / Latest macOS (Ventura, Sonoma) | | **CPU** | x64, Intel/AMD | Apple Silicon (M1, M2, M3, M4) only | | **RAM** | 8 GB / 16 GB+ | 8 GB / 16 GB+ | | **Disk** | SSD / Fast SSD | SSD / NVMe | | **Permissions** | Install & read/write files (Admin recommended) | Install apps, Full Disk Access recommended | --- ## Download & Installation ### Windows Installation #### Step 1: Get the Installer 1. Open your browser and go to **dropstone.io**. 2. Navigate to the **Downloads** section. 3. Select **Windows** and download the `.exe` file. 4. Save the installer to an accessible location (e.g., **Downloads folder**). #### Step 2: Install Dropstone 1. Double-click the installer file. 2. Accept the **license agreement**. 3. Choose an installation directory (default is recommended). 4. Click **Install** and wait for setup to complete. 5. Launch Dropstone via **Start Menu** or **Desktop shortcut**. --- ### macOS Silicon Installation #### Prerequisites **Homebrew is required** for this installation method. If you don't have Homebrew installed, open **Terminal** and run: ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` #### For Existing Users If you already have Dropstone installed, upgrade to the latest version: ```bash brew upgrade --cask dropstone ``` #### Installation Steps **1. Add Dropstone Tap** Add the official Dropstone repository to Homebrew: ```bash brew tap blankline-org/dropstone ``` **2. Install Dropstone** Install the Dropstone desktop application: ```bash brew install --cask dropstone ``` **3. Launch Dropstone** Open Dropstone from **Launchpad**, **Applications folder**, or Spotlight. If macOS blocks the app (Gatekeeper), go to **System Settings → Privacy & Security → Open Anyway**.