> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Your First Session
> Start your first Devin session: choose Ask or Agent mode, pick a repository and agent, use @ mentions, and try first-time prompt ideas.
export const PromptBlock = ({children, type, agent, intent, playbookId}) => {
var utm = 'utm_source=docs&utm_medium=use-case-gallery&utm_campaign=prompt-block';
var tag = 'docs-use-case-gallery';
var agentParams = (agent ? '&agent=' + agent : '') + (intent ? '&intent=' + intent : '') + (playbookId ? '&playbookId=' + playbookId : '');
var label = type === 'schedule' ? 'Schedule in Devin' : type === 'playbook' ? 'Create Playbook' : type === 'knowledge' ? 'Add to Knowledge' : agent === 'advanced' ? 'Try in Devin' : agent === 'dana' ? 'Try in Dana' : agent === 'ada' ? 'Try in Ask Devin' : 'Try in Devin';
var buildUrl = function (text) {
var encoded = encodeURIComponent(text);
if (type === 'schedule') return 'https://app.devin.ai/settings/schedules/create?' + utm + agentParams + '&prompt=' + encoded;
if (type === 'playbook') return 'https://app.devin.ai/settings/playbooks/create?' + utm + '&body=' + encoded;
if (type === 'knowledge') return 'https://app.devin.ai/knowledge?' + utm + '&body=' + encoded;
if (agent === 'ada') return 'https://app.devin.ai/search?' + utm + '&noSubmit=true&prompt=' + encoded;
return 'https://app.devin.ai/?tags=' + tag + '&' + utm + agentParams + '&prompt=' + encoded;
};
const ref = React.useRef(null);
const [href, setHref] = React.useState('#');
React.useEffect(() => {
if (!ref.current) return;
var codeEl = ref.current.querySelector('pre code');
if (codeEl) {
var text = codeEl.textContent.trim();
if (text) setHref(buildUrl(text));
}
var header = ref.current.querySelector('[data-component-part="code-block-header"]');
if (header && !header.querySelector('.prompt-block-devin-link')) {
var link = document.createElement('a');
link.href = href;
link.target = '_blank';
link.rel = 'noopener noreferrer';
link.className = 'prompt-block-devin-link';
link.style.cssText = 'display:inline-flex;align-items:center;gap:6px;text-decoration:none;color:#fff;font-size:11px;font-weight:500;padding:4px 10px;border-radius:6px;white-space:nowrap;background:#317CFF;transition:background 0.2s;margin-left:8px;';
link.innerHTML = ' ' + label;
link.onmouseenter = function () {
link.style.background = '#2968D9';
};
link.onmouseleave = function () {
link.style.background = '#317CFF';
};
header.appendChild(link);
}
var existingLink = ref.current.querySelector('.prompt-block-devin-link');
if (existingLink && href !== '#') existingLink.href = href;
});
return
{children}
;
};
Before you start your first session, make sure you've [indexed](/onboard-devin/index-repo) and [set up](/onboard-devin/environment) your repositories. These are the foundational steps that help Devin understand and work with your codebase.
Now that you're all set up, kick off your first Devin session! This guide will walk you through the new session interface and help you understand the best ways to interact with Devin.
Prefer working from your terminal? [Devin CLI](/cli) lets you start sessions right from the command line. Install in 2 minutes with `curl -fsSL https://cli.devin.ai/install.sh | bash`.
## Understanding the Devin Session Page
When you start a new session, you'll see two primary modes: **Ask** and **Agent**.
Unless you already have a fully scoped plan, we recommend starting with Ask to work with Devin on constructing a plan, then moving to Agent mode to execute it.
### Ask Mode
**Ask Devin** is a lightweight mode for exploring your codebase and planning tasks with Devin, without making changes to the actual code. Ask Devin now supports both asking questions and planning:
* **Ask questions** about how your code works. Uses advanced code search to produce detailed, accurate, and well-cited answers.
* **Plan tasks** by scoping and planning work before implementation. Devin generates context-rich prompts for Agent sessions.
When you start a Devin session from Ask Devin, the session status is visible directly in the conversation.
#### Triggering Ask Mode
You can trigger Ask mode from the main page or from a DeepWiki page.
For Ask mode from the main page, toggle to Ask mode and select the repository/repositories you want to ask about.
For Ask mode from a DeepWiki page, type a query in the chat input at the bottom of the page and click Ask. This will automatically scope Devin's knowledge to that repository specifically.
Learn more in our [Ask Devin guide](/work-with-devin/ask-devin).
Once you've worked with Devin to understand the problem and create a plan, you're ready to move to Agent mode.
### Agent Mode
Agent mode is Devin's full autonomous mode where it can write code, run commands, browse the web, and complete complex tasks end-to-end. Use Agent mode when you're ready to:
* Implement features or fix bugs
* Create pull requests
* Run tests and debug issues
* Perform multi-step tasks that require code changes
#### Choosing an agent
The agent selector in the message box controls which agent runs your session. You can change it when you start a session or switch mid-session.
| Agent | Use it for |
| - | - |
| **Lite** | Simple, well-scoped tasks at the lowest cost. |
| **Normal** | The default. Balances cost and capability for everyday work. |
| **Ultra** | The hardest tasks. Most capable, and significantly more expensive. |
| **Fusion** | Frontier-level results at lower cost, by pairing a frontier model with a cost-efficient one. |
| **SWE-2** (research preview) | Cognition's own software engineering model. Pick a reasoning effort of **Medium**, **High**, or **Max**. |
Higher capability uses more powerful models and costs more. Research previews are available for a limited time and aren't optimized for everyday use. Admins control which agents are available, so you may not see every option; enterprise admins enable SWE-2 (Preview) in Settings.
In Slack, switch agents with [mode keywords](/integrations/slack) such as `!lite`, `!ultra`, `!fusion`, or `!swe2`.
#### Triggering Agent Mode
You can trigger Agent mode from the main page or from an Ask Devin session. When a session is started from Ask Devin, its status is displayed in the Ask Devin conversation so you can track progress.
For tasks that are not fully scoped, we recommend:
* Start with **Ask mode** to plan out the task
* **Construct a Devin Prompt**, which will draw from your Ask session to create a scoped plan
* Click **Send to Devin** to move to Agent mode and execute the task
This flow is shown below:
For Agent mode from the main page, toggle to Agent mode and select the repository/repositories you want to work with.
When starting an Agent session, you'll configure a few options: selecting a Repository and selecting an Agent.
#### Selecting a Repository
Select the repository you want Devin to work with. Click the repository selector to see all repositories that have been [added to Devin's machine](/onboard-devin/environment).
Selecting a repository ensures Devin:
* Has access to your codebase and can make changes
* Uses the correct branch as a starting point
* Can create pull requests to the right repository
#### Selecting an Agent
You can choose which agent configuration Devin uses for your session. Different agents may have different capabilities or be optimized for specific types of tasks.
Available agents include:
* **Devin** (default) — A general-purpose AI software engineer for building features, fixing bugs, refactoring code, and most development tasks.
* **Fast Mode** — An optimized mode for quick, well-scoped tasks.
* **[Data Analyst](/work-with-devin/data-analyst)** (DANA) — A data analyst agent optimized for querying databases, analyzing data, and creating visualizations. To use it, open the **Mode** submenu in the agent picker and select **Data**.
If you're unsure which agent to use, the default Devin agent works well for most tasks.
You don't need to start a new session to change modes. You can switch the agent mid-session using the agent toggle next to the message input on the session page — the change takes effect with your next message. In Slack, you can switch modes mid-session by starting a message with `!ultra`, `!fast`, `!lite`, `!fusion`, `!swe`, or `!normal` (see [Slack mode keywords](/integrations/slack)).
## Using @ Mentions
Use `@` mentions to give Devin specific context about files, repositories, or other resources. When you type `@` in the chat input, you'll see a dropdown of available mentions:
* **@Repos** - Reference a specific repository
* **@Files** - Reference a specific file in your codebase
* **[@Macros](/product-guides/knowledge)** - Reference a macro for a Knowledge entry
* **[@Playbooks](/product-guides/creating-playbooks)** - Reference a team or community playbook, which are detailed prompt templates that can be used to guide Devin's behavior
* **[@Skills](/product-guides/skills)** - Reference a skill defined in your repository (reusable procedures committed as `SKILL.md` files)
* **[@Secrets](/product-guides/secrets)** - Reference a specific secret (e.g. API keys, credentials, etc.) from Devin's session manager
* **@Sessions** - Reference a previous Devin session for context
@ mentions help Devin understand exactly what you're working with and reduce ambiguity in your prompts.
## Scoping Your First Session
Start with tasks that have **clear success criteria** and **provide Devin with the context it needs** — just as you would when handing off work to a teammate. As you get comfortable, try progressively more complex tasks. We've seen users work with Devin on everything from fixing small bugs to targeted refactors to large-scale migrations and building entire features from scratch.
As a rule of thumb: if a task would take you three hours or less, Devin can most likely do it. For larger projects, break them into focused sessions and run them in parallel with [managed Devins](/work-with-devin/advanced-capabilities#managed-devins).
## First-time Prompt Ideas
```Adding a new API endpoint theme={null}
Create a new endpoint /users/stats that returns a JSON object with user count and average signup age.
Use our existing users table in PostgreSQL.
You can reference the /orders/stats endpoint in statsController.js for how we structure responses.
Ensure the new endpoint is covered by the StatsController.test.js suite.
```
```Small frontend features theme={null}
In UserProfileComponent, add a dropdown that shows a list of user roles (admin, editor, viewer).
Use the styling from DropdownBase.
When a role is selected, call the existing API to set the user role.
Validate by checking that the selection updates the user role in the DB. Refer to your skills for how to test properly.
```
```Write unit tests theme={null}
Add Jest tests for the AuthService methods: login and logout.
Ensure test coverage for these two functions is at least 80%.
Use UserService.test.js as an example.
After implementation, run `npm test -- --coverage` and verify the coverage report shows >80% for both functions.
Also confirm that tests pass with both valid and invalid credentials, and that logout properly clears session data.
```
```Migrating or refactoring existing code theme={null}
Migrate logger.js from JavaScript to TypeScript.
We already have a tsconfig.json and a LoggerTest.test.js suite for validation.
Make sure it compiles without errors and make sure not to change the existing config!
After migration, verify by:
1) running `tsc` to confirm no type errors
2) running the test suite with `npm test LoggerTest.test.js` to ensure all tests pass
3) checking that all existing logger method calls throughout the codebase still work without type errors.
```
```Updating APIs or database queries theme={null}
We're switching from pg to sequelize (read https://sequelize.org/api/v6/identifiers).
Please update the UserModel queries to use Sequelize methods.
Refer to OrderModel for how we do it in this codebase.
After implementation, verify by:
1) running `npm run test:integration UserModel.test.js` to check all integration tests pass
2) confirming query performance hasn't degraded by checking execution time on a test dataset of 1000 users
3) validating that all CRUD operations still maintain data integrity by running `npm run test:e2e user-flows.test.js`
```
```txt Quick PR theme={null}
## Overview
Make a small, focused pull request for the change I describe.
## What's Needed From User
- The repository to change
- A description of the change, plus any metadata to include in the PR (e.g. a Linear or Jira ticket ID)
## Procedure
1. Study the request and the relevant code, and share a short plan before making changes.
2. Make only the requested changes.
3. Run the repository's lint and typecheck commands for the files you changed, and fix any failures.
4. Open a pull request whose description follows the repository's PR template.
5. Fix CI failures and address review feedback by pushing new commits to the same branch.
## Specifications
- PR contains no stray or unrequested changes
- Lint and typecheck pass
- PR description includes any metadata I provided
```
Devin handles branching, PR creation, and CI monitoring with its built-in workflow, so the playbook only needs to describe the task. See [Creating Playbooks](/product-guides/creating-playbooks) to save this prompt as a Playbook, and [Pull Request Templates](/integrations/pr-templates) to control what goes into the PR description.
If you'd like to dig in to some more detailed examples of what Devin can do (and how), check out our **use cases**.
Explore practical examples across engineering workflows — each includes prompts you can try immediately.
## After Your Session
Once Devin finishes, open [Session Insights](/product-guides/session-insights) and click **Generate Analysis** — you'll get a timeline of what happened, actionable feedback, and an improved prompt you can use for similar tasks in the future.
## Next Steps
Once you're comfortable with basic sessions, explore these resources to get more out of Devin:
Connect Devin to your existing tools like GitHub, Slack, Jira, and more.
Learn how to use Playbooks to implement tasks.
Add skills to teach Devin your team's practices and procedures.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
#### Triggering Ask Mode
You can trigger Ask mode from the main page or from a DeepWiki page.
For Ask mode from the main page, toggle to Ask mode and select the repository/repositories you want to ask about.
For Ask mode from a DeepWiki page, type a query in the chat input at the bottom of the page and click Ask. This will automatically scope Devin's knowledge to that repository specifically.
Learn more in our [Ask Devin guide](/work-with-devin/ask-devin).
Once you've worked with Devin to understand the problem and create a plan, you're ready to move to Agent mode.
### Agent Mode
Agent mode is Devin's full autonomous mode where it can write code, run commands, browse the web, and complete complex tasks end-to-end. Use Agent mode when you're ready to:
* Implement features or fix bugs
* Create pull requests
* Run tests and debug issues
* Perform multi-step tasks that require code changes
#### Choosing an agent
The agent selector in the message box controls which agent runs your session. You can change it when you start a session or switch mid-session.
| Agent | Use it for |
| - | - |
| **Lite** | Simple, well-scoped tasks at the lowest cost. |
| **Normal** | The default. Balances cost and capability for everyday work. |
| **Ultra** | The hardest tasks. Most capable, and significantly more expensive. |
| **Fusion** | Frontier-level results at lower cost, by pairing a frontier model with a cost-efficient one. |
| **SWE-2** (research preview) | Cognition's own software engineering model. Pick a reasoning effort of **Medium**, **High**, or **Max**. |
Higher capability uses more powerful models and costs more. Research previews are available for a limited time and aren't optimized for everyday use. Admins control which agents are available, so you may not see every option; enterprise admins enable SWE-2 (Preview) in Settings.
In Slack, switch agents with [mode keywords](/integrations/slack) such as `!lite`, `!ultra`, `!fusion`, or `!swe2`.
#### Triggering Agent Mode
You can trigger Agent mode from the main page or from an Ask Devin session. When a session is started from Ask Devin, its status is displayed in the Ask Devin conversation so you can track progress.
For tasks that are not fully scoped, we recommend:
* Start with **Ask mode** to plan out the task
* **Construct a Devin Prompt**, which will draw from your Ask session to create a scoped plan
* Click **Send to Devin** to move to Agent mode and execute the task
This flow is shown below:
For Agent mode from the main page, toggle to Agent mode and select the repository/repositories you want to work with.
When starting an Agent session, you'll configure a few options: selecting a Repository and selecting an Agent.
#### Selecting a Repository
Select the repository you want Devin to work with. Click the repository selector to see all repositories that have been [added to Devin's machine](/onboard-devin/environment).
Selecting a repository ensures Devin:
* Has access to your codebase and can make changes
* Uses the correct branch as a starting point
* Can create pull requests to the right repository
#### Selecting an Agent
You can choose which agent configuration Devin uses for your session. Different agents may have different capabilities or be optimized for specific types of tasks.
Available agents include:
* **Devin** (default) — A general-purpose AI software engineer for building features, fixing bugs, refactoring code, and most development tasks.
* **Fast Mode** — An optimized mode for quick, well-scoped tasks.
* **[Data Analyst](/work-with-devin/data-analyst)** (DANA) — A data analyst agent optimized for querying databases, analyzing data, and creating visualizations. To use it, open the **Mode** submenu in the agent picker and select **Data**.
@ mentions help Devin understand exactly what you're working with and reduce ambiguity in your prompts.
## Scoping Your First Session
Start with tasks that have **clear success criteria** and **provide Devin with the context it needs** — just as you would when handing off work to a teammate. As you get comfortable, try progressively more complex tasks. We've seen users work with Devin on everything from fixing small bugs to targeted refactors to large-scale migrations and building entire features from scratch.