Your First Session

Start your first session and see what Opulent can do

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 Opulent' : type === 'playbook' ? 'Create Playbook' : type === 'knowledge' ? 'Add to Knowledge' : agent === 'advanced' ? 'Try in Opulent' : agent === 'dana' ? 'Try in Data Analyst' : agent === 'ada' ? 'Try in Ask Opulent' : 'Try in Opulent'; var buildUrl = function (text) { var encoded = encodeURIComponent(text); if (type === 'schedule') return 'https://platform.opulentia.ai/settings/schedules/create?' + utm + agentParams + '&prompt=' + encoded; if (type === 'playbook') return 'https://platform.opulentia.ai/settings/playbooks/create?' + utm + '&body=' + encoded; if (type === 'knowledge') return 'https://platform.opulentia.ai/knowledge?' + utm + '&body=' + encoded; if (agent === 'ada') return 'https://platform.opulentia.ai/search?' + utm + '&noSubmit=true&prompt=' + encoded; return 'https://platform.opulentia.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-opulent-link')) { var link = document.createElement('a'); link.href = href; link.target = '_blank'; link.rel = 'noopener noreferrer'; link.className = 'prompt-block-opulent-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-opulent-link'); if (existingLink && href !== '#') existingLink.href = href; }); return

Now that you're all set up, kick off your first Opulent Session! A session is the unit of work you assign to Opulent — a single execution inside it is called a Run. This guide walks you through the new session interface and the best ways to interact with Opulent.

Understanding the Opulent Session Page

When you start a new session, you'll see two primary modes: Ask and Agent.

Ask Mode

Ask Opulent is a lightweight mode for exploring your codebase and planning tasks with Opulent, without making changes to the actual code. Ask Opulent 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. Opulent generates context-rich prompts for Agent sessions.

When you start an Opulent session from Ask Opulent, the session status is visible directly in the conversation.

Triggering Ask Mode

You can trigger Ask mode from the main page or from a Knowledge Map 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 Knowledge Map page, type a query in the chat input at the bottom of the page and click Ask. This automatically scopes Opulent's Knowledge Map to that repository specifically. Knowledge Map coverage of public GitHub repositories is available today; generated maps for private client workspaces are Planned.

Learn more in our Ask Opulent guide.

Once you've worked with Opulent to understand the problem and create a plan, you're ready to move to Agent mode.

Agent Mode

Agent mode is Opulent'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

Triggering Agent Mode

You can trigger Agent mode from the main page or from an Ask Opulent session. When a session is started from Ask Opulent, its status is displayed in the Ask Opulent 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 an Opulent Prompt, which will draw from your Ask session to create a scoped plan
• Click Send to Opulent 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 Opulent to work with. Click the repository selector to see all repositories that have been added to Opulent's machine.

Selecting a repository ensures Opulent:

• 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 configuration Opulent uses for your session. Different configurations may have different capabilities or be optimized for specific types of tasks.

Available configurations include:

• Opulent (default) — A general-purpose Autonomous Knowledge Worker for building features, fixing bugs, refactoring code, and most engineering and knowledge-work tasks.
• Fast Mode — A lightweight configuration optimized for quick, well-scoped tasks.
• Data Analyst — A capability lane optimized for querying databases, analyzing data, and creating visualizations. Data Analyst is a lane within Opulent, not a separate agent.

Using @ Mentions

Use @ mentions to give Opulent 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 - Reference a macro for a Knowledge entry
• @Playbooks - Reference a team or community playbook, which are detailed prompt templates that can be used to guide Opulent's behavior
• @Skills - Reference a skill defined in your repository (reusable procedures committed as SKILL.md files)
• @Secrets - Reference a specific secret (e.g. API keys, credentials, etc.) from Opulent's session manager
• @Sessions - Reference a previous Opulent session for context

@ mentions help Opulent 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 Opulent 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 Opulent on everything from fixing small bugs to targeted refactors to large-scale migrations and building entire features from scratch.

First-time Prompt Ideas

  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.
  ```
</PromptBlock>

  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 Knowledge for how to test properly.
  ```
</PromptBlock>

  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.
  ```
</PromptBlock>

  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.
  ```
</PromptBlock>

  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`
  ```
</PromptBlock>

  ## What's Needed From User
  - The repository to create a pull request

  ## Procedure
  ### Prepare your workspace
  1. Navigate to the relevant repository on your machine (clarify with the user if you can't figure it out).
      - Check out the main branch and note down the name of the main branch.
      - Checkout to a new branch since you'll be making a pull request. The name of the branch has to be of the format `opulent/<timestamp>-<your-branch-name>`. For example `opulent/1700000000-fix-popup`. Run `git remote -v && git pull && git checkout -b opulent/$(date +%s)-{branch-name}` and replace `{branch-name}` with the name of the branch you want to create.
  2. Study the request, codebase, and plan out the changes
      - Review the most relevant files and code sections, identifying relevant snippets.
      - Inform the user of your plan
  ### Work on the PR itself
  3. Make the code changes
      - Don't change anything that wasn't specifically requested by the user
  4. Make the PR
      - Commit and push the changes and tell the user.
      - See advice section for the exact command to make the PR
      - Make a pull request & review the pr to make sure it looks OK.
      - Ensure all GitHub actions pass successfully & make necessary changes until they do
      - Send the PR link to the user and summarize what you changed.
  5. Address any feedback from the review; send the PR link again every time you make any changes
      - If you need to make updates, just push more commits to the same branch; don't create a new one


  ## Task Specification
  - PR link is included in your messages to the user
  - PR was reviewed after creation
  - PR does not include any stray changes
  - PR does not change anything that wasn't specifically requested by the user
  - PR description should include a summary of the changes, formatted as a checklist
  - PR description should mention that the code was written without testing, and include - [ ] Test the changes as an item
  - PR description should include the following footer: "This PR was written by [Opulent](https://opulentia.ai/) :angel:"
  - PR description should include any metadata that the user has provided (e.g. linear ticket tags in the appropriate syntax)
  - PR description should not be malformatted (use --body-file instead of --body if the newlines are garbled!)

  ## Forbidden Actions
  - Do NOT try to access github.com through the browser, you will not be authenticated.
  - NEVER force push on branches! Prefer merging over rebasing so that you don't lose any work.
  - Do NOT push directly to the main branch.

  ## Advice and Pointers
  - Double check the name of the main branch (which could be `main` or `master`) using `git branch`.
  - For repos with CI/CD on github actions, you can check build logs using the gh cli. if you're asked to fix a build/fix lint, you should start by looking at recent build logs
  - Check `git status` before committing or adding files.
  - Use `git diff` to see what changes you have made before committing.
  - If you're updating an existing repo, use `gh cli` to make pull requests.
  - Send the PR link to the user every time you update & ask them to re-review so that it's convenient for them
  - You should already be authorized to access any repositories the user tells you about. If not, ask the user for access.
  ```
</PromptBlock>

If you'd like to dig in to some more detailed examples of what Opulent can do (and how), check out our tutorials.

After Your Session

Once Opulent finishes, open 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 Opulent: