Core concepts

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.

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:

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:

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, connect to external services with MCP servers, and offload work to subagents. For the complete list of built-in tools, see Built-in 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. 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 for external services, skills for workflows, and subagents 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, resume, and fork 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, 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 <id>.

# 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, 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, not in chat messages. The chat-message version gets compacted out; the AGENTS.md version is reloaded every session.
• Skills load on demand. Dropstone sees skill descriptions at session start but only loads the full content when a skill is invoked.
• Subagents 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.

/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 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. For example:

{
  "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.

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:

fix the login bug

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:

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:

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:

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:

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