Welcome to Roksta! 🤘

Model-efficient AI coding built on task decomposition.

Most tools use a single, expensive model for everything, encouraging assumptions and losing clarity over long sessions. This forces repeated iterations and quickly drives up costs.

Roksta decomposes work into simpler tasks and routes each one to an appropriate LLM. This reduces unnecessary spend without compromising performance, while clarity and transparency minimise rework. The same architecture improves reliability and scalability as projects grow.

Here's what we believe an AI coding assistant should and shouldn't do:

👍 They should:

• Performance: Reduce complexity via task decomposition.
• Cost & Speed: Use fast, low-cost models for simpler tasks.
• Clarity: Ask for details instead of assuming.
• Transparency: Explain the plan before coding.

👎 They shouldn't:

• Degrade in performance as the session grows.
• Be locked to a single LLM provider.
• Have expensive subscriptions.
• Impose arbitrary usage limits.

Roksta delivers all the above with simple pay-as-you-go pricing — no subscription required.

Roksta's architecture is informed by research on long-horizon task decomposition, including work such as Solving a Million-Step LLM Task with Zero Errors.

Table of Contents

• Installation & Setup
• Usage
• Recommended Workflows
• Command Reference
• Command Line Parameters
• Troubleshooting
• Terms & Conditions

Installation & Setup

Prerequisites

• Python 3.11 or later
• pipx installed

Supported Platforms

• Linux (x86_64, aarch64)
• macOS (x86_64, arm64)
• Windows (64-bit)

Installation

pipx install roksta
pipx ensurepath

Launching Roksta

Navigate to your project's root folder and run:

roksta

Once launched, you will see a welcome screen and instructions on how to get started.

Initial Setup

Run the /init command in Roksta to initialise the codebase. This step prepares the configuration files and indexes your project structure. This can take a few minutes depending on the size of your project. However, it only needs to be done once and significantly speeds up Roksta during subsequent runs.

The command also creates a .roksta folder in the project directory and adds it to the .gitignore file. It also creates .rokstarc and .rokstaignore files in the project root folder that provides Roksta with project specific configuration details.

We recommend that you edit .rokstaignore to make it specific for your project. A better specified file will improve Roksta's speed and reduce token usage which ultimately reduces the cost of using Roksta.

You're now ready to start using Roksta! 🤘

PS: Roksta also supports an AGENTS.md file in the project root folder.

Usage

Setting Goals

Once Roksta has been initialised, you can tell it what you want it to do by issuing the /goal command and then specifying your goal in the input box. The input box accepts multi-line inputs, so you will need to press Ctrl+Enter or Ctrl+S to submit your goal. macOS users may use the Cmd key instead of Ctrl.

Directives can be used to control how Roksta behaves. They are:

• #full-auto: Instructs Roksta to work on the goal and apply changes without requiring any human intervention. It's therefore important to ensure that the goal is well specified.

• #clarify: Force goal clarification even in full-auto mode.

• #no-clarify: Skip goal clarification.

• #yolo: Allow Roksta to run any shell command without asking for permission, can be useful when combined with the #full-auto directive.

• #thinking(<level>): Adjusts the AI's computational effort for the task. The following class of models will be used by default: gpt-5-mini, grok-4-fast, gemini-2.5-flash, claude-haiku-4.5.

  • <level> can be:
    • fast: Uses faster models (e.g. mini, fast, flash) or fast inference providers (e.g. Cerebras) or a combination to deliver results faster.
    • more: Uses models that think more. Useful for more complex tasks where deeper analysis is required. The following types of models used will be: gpt-5, grok-4, gemini-2.5-pro, claude-sonnet-4.5.
    • max: Uses the most powerful models available. The following types of models used will be: gpt-5.2 (xhigh), claude opus 4.5, gemini-3-pro.
  • If multiple #thinking directives are used in a single goal, the last one specified will take precedence.
  • Example:

    Refactor the authentication module. #thinking(more)
    

  • Note: If thinking is not set, Roksta will dynamically choose the thinking level depending on the goal's difficulty.

• #llm-family(<family>): Specifies the preferred LLM family for the task (case-insensitive). Accepted values:

  • OpenAI
  • Gemini
  • Anthropic
  • xAI

  This directive guides Roksta's model selection to balance performance and cost. Example usage:

  Refactor data pipeline. #llm-family(Gemini)
  

• #commit: Automatically commits the changes made by Roksta to your local git repository after they have been applied. This does not push the changes to a remote repository. Can be overridden by the #no-commit directive.

• #no-commit: Prevents all forms of automatic committing for the specific goal to which it's applied, overriding any global auto-commit settings or the #commit directive.

• #test: Temporarily force running of tests for this goal run if a test command is configured in .rokstarc. If no test command is configured a warning is printed and no tests are attempted. This directive only affects the current goal execution and does not persist to project configuration.

• #no-test: Prevents automatic running of tests even if testing has been enabled via the /testing on command. Takes precedence over #test if both are present.

• #build: Temporarily force a build for this goal run if a build command is configured in .rokstarc. If no build command is configured a warning is printed and no build is attempted. This directive only affects the current goal execution and does not persist to project configuration.

• #no-build: Temporarily skip building for this goal run. Takes precedence over #build if both are present. This directive only affects the current goal execution and does not persist to project configuration.

The following directives can be used to tune the context window to help improve performance:

• #focus(<pattern>): Add a file or glob pattern to include as context for understanding the goal.
• #ignore(<pattern>): Exclude files from consideration entirely.

If multiple directives of the same type are used, all specified patterns will be merged. Each directive should be on its own line, and directives may be placed anywhere in the goal text.

Recommended Workflows

We recommend using the following workflows when working with Roksta.

Start with /goal

This is the primary way to get Roksta to work on a specific task, particularly when you have a clear objective in mind, like adding a new feature or refactoring existing code.

1. Submit a goal using the /goal command. Don't make goals too ambitious, if it would take an experienced developer over one week to complete it, it's probably worth breaking the goal down into smaller chunks. Ideally, something that would take 1-3 days of coding.

2. Don't worry about being vague when specifying your goal. Roksta will ask clarifying questions if it needs more information. If you're not sure about a question, just say so and Roksta will pick a sensible default.

3. Review the proposed plan and provide feedback. You can ask Roksta to make changes to the plan if you so wish.

Start with /chat

If you're not sure about the problem you're trying to solve (e.g. a bug or a design question), or if you want to explore the codebase before setting a goal, start with the /chat command.

1. Start a chat session using the /chat command to discuss and analyse the bug for example.

2. Once you and Roksta have a good understanding of the issue, ask Roksta to launch a goal to fix the bug. It will start a new goal and prepopulate the input box with a proposed goal statement. You can edit this if you wish before submitting it.

3. Roksta will include the #no-clarify directive automatically when launching the goal from chat mode but you can remove this if you want Roksta to ask clarifying questions about the bug fix.

Tips:

• Activate a git branch for feature or bug fix work to keep changes isolated.
• Review code changes using your IDE or a diff tool before accepting them.
• Accept/edit/discard changes as you see fit and commit.

Command Reference

Below are the commands that are available in Roksta. Commands that require the user to be logged in are noted accordingly.

/add-funds

• Requires login

• Description: Adds funds to your account. All amounts are in USD. You cannot add less than $5.00 USD per transaction.

• Usage: /add-funds <amount_usd> (enter the amount in USD)

• Example: /add-funds 10 will add $10.00 USD to your account balance.

/auto-charge

• Requires login

• Description: Configures automatic top-up of your account balance. When enabled, Roksta will automatically add funds (USD) to your account if your balance drops below a specified threshold.

• Usage: /auto-charge <on|off|status> [charge_amount_usd trigger_balance_usd]

• Subcommands:

  • on: Enables auto-charge. If charge_amount_usd and trigger_balance_usd are not provided, it uses the default values ($10.00 USD charge amount, $2.00 USD trigger balance) or the last saved values.
  • off: Disables auto-charge.
  • status (or no parameters): Show the current auto-charge configuration.

• Parameters:

  • <on|off|status>: (Required)
  • [charge_amount_usd]: (Optional) The amount in USD to be automatically charged to your payment method. Minimum $5.00 USD. If provided, trigger_balance_usd must also be provided. Defaults to $10.00 USD if enabling with on and no custom values are set.
  • [trigger_balance_usd]: (Optional) The balance threshold in USD below which an auto-charge will be triggered. Minimum $1.00 USD. If provided, charge_amount_usd must also be provided. Defaults to $2.00 USD if enabling with on and no custom values are set.

• Example: /auto-charge on 15 5 will automatically fund your account with $15.00 USD when the balance drops below $5.00 USD.

• Notes:

  • If you wish to specify charge_amount_usd and trigger_balance_usd, both must be provided.

/auto-commit

• Description: Enables, disables, or reports the status of automatic commits for this project. If no subcommand is provided, it defaults to status. The setting is stored in the project configuration file at <project-root>/.rokstarc as the top-level key auto_commit.

• Usage: /auto-commit <on|off|status>

• Example: /auto-commit on

/building

• Description: Manage project-specific build configuration stored under the top-level building key in your project config file. The /building command records two configuration values (enabled and command) in <project-root>/.rokstarc. It does NOT run your build; it only saves the command Roksta can reference later.

• Usage: /building <on|off|set|clear|status> ["build command"]

• Subcommands:

  • status (or no parameters): Show the current values of building.enabled and building.command.
  • on: Enable building by setting building.enabled = true and persisting the project config.
  • off: Disable building by setting building.enabled = false and persisting the project config.
  • set "command": Save the build command and set building.enabled = true. The command parameter is required and must be non-empty. Example: /building set "npm run build".
  • clear: Remove or clear the building configuration (sets enabled = false and empties command). If no config file exists the command will clear the in-memory project config instead.

• Behaviour:

  • If no project config file exists the command will create one and initialise it with sensible defaults.
  • If the project config file contains invalid JSON, /building will refuse to operate and will prompt you to fix .rokstarc manually.

• Examples:

  /building status
  /building on
  /building off
  /building set "npm run build"
  /building clear
  

/chat

• Requires login

• Description: Starts an interactive chat session where you can ask questions about your codebase. Passing the optional continue argument maintains the context of the previous chat session. Roksta can read your files to provide contextually-aware answers. This command is for querying and understanding your code; to apply code changes, use the /goal command. To exit the chat session, use the /end command (/quit and /exit will also work) or press Ctrl+R.

• Usage: /chat [continue]

Specify continue after /chat to maintain the context of the previous chat session. This is useful when the new chat session is related or builds upon the previous session.

• Commands The chat interface supports the following slash commands:
  • /thinking <level>: Adjusts the AI's computational effort. Accepted levels:
    • default
    • fast
    • more
    • max
  • /save [filename]: Saves the chat transcript; the filename is optional.
  • /end, /exit or /quit: Ends the chat session.
  • /help: Displays chat related help information.

/clear

• Description: Clears the output area.

/dev-rate

• Description: Sets the developer rate in USD per hour, used to calculate developer savings. It displays the current rate if called without providing a rate.

• Usage: /dev-rate [hourly_rate_usd] (enter the hourly rate in USD)

• Example: /dev-rate 75 sets a rate of $75.00 USD/hour.

/epic

• Requires login

• Description: Decomposes the provided epic into smaller goals and writes them out to a Markdown file. Generated goals can then be worked through sequentially.

• Usage: /epic

• Parameters: None. Arguments such as continue are not supported.

/feedback

• Requires login

• Description: Submits feedback regarding the application.

/goal

• Requires login

• Description: Starts the process by which you can ask Roksta to work on achieving a specific goal. Click here to understand how to set goals for Roksta to work on. Passing the optional continue argument maintains the context of the previously completed goal.

• Usage: /goal [continue]

Specify continue after /goal to maintain the context of the previous goal. This is useful when the new goal is related or builds upon the previous goal.

/help

• Description: Displays all available commands along with a help message.

/init

• Description: Initialises the codebase. Use this command if Roksta has not yet been initialised. This may take a few minutes and only needs to be done once. If you omit this step, Roksta will automatically run the initialisation step when you give it your first goal.

/linting

• Description: Manage project-specific linting configuration stored under the top-level linting key in your project config file. The /linting command records three configuration values (enabled, check and fix) in <project-root>/.rokstarc. It does NOT run linters; it only saves the commands Roksta can reference later.

• Usage: /linting <on|off|set|clear|status> ["check command"] ["fix command"]

• Subcommands:

  • status (or no parameters): Show the current values of linting.enabled, linting.check and linting.fix.
  • on: Enable linting by setting linting.enabled = true and persisting the project config.
  • off: Disable linting by setting linting.enabled = false and persisting the project config.
  • set "check" ["fix"]: Save a check command and an optional fix command, and set linting.enabled = true. The check parameter is required and must be non-empty. Example: /linting set "flake8 ." "black .".
  • clear: Remove or clear the linting configuration (sets enabled = false and empties check/fix). If no config file exists the command will clear the in-memory project config instead.

• Behaviour:

  • If no project config file exists the command will create one and initialise it with sensible defaults.
  • If the project config file contains invalid JSON, /linting will refuse to operate and will prompt you to fix .rokstarc manually.

• Examples:

  /linting status
  /linting on
  /linting off
  /linting set "flake8 ." "black ."
  /linting clear
  

/load-goals

• Requires login

• Description: Loads goals from a Markdown file and immediately starts iterating through them .

• Usage: /load-goals <filename-or-path>

• Parameters: Exactly one filename or relative filepath. A bare filename is resolved under <project-root>/.roksta; a relative filepath is resolved under <project-root>. Absolute paths and paths that resolve outside the project root, including unsafe .. traversal or external symlinks, are rejected.

Note: The format of a file with goals is straightforward. Each goal should start with # ===GOAL=== on a line by itself, followed by the goal text on subsequent lines. The goal text may contain directives such as #full-auto or #clarify. Each goal should end with a blank line before the next # ===GOAL=== line.

/logging

• Description: Manage tool call logging configuration. Enabling this will log tool call details to .roksta/tool_call.log immediately and across sessions.

• Usage: /logging <on|off|status>

• Subcommands:

  • on: Enables tool call logging and saves the preference.
  • off: Disables tool call logging for future sessions and saves the preference.
  • status (or no parameters): Displays the current logging status and usage information.

/login

• Description: Logs you in. Logging in is a prerequisite to use Roksta.

  Note: Once you log in, Roksta will store your login token in the .roksta.json file in your home directory. It will use this token to auto-login every time to start up Roksta. If you don't want it to log you in automatically, set the value of auto to false.

/mcp

• Description: Lists and reloads configured MCP servers.

• Usage: /mcp <list|reload>

• Subcommands:

  • list: Lists the currently configured MCP servers and their connection status.
  • reload: Reloads the MCP server configuration from <project-root>/.roksta/mcp.json without restarting Roksta.

Create <project-root>/.roksta/mcp.json with a top-level mcpServers object. Each server definition uses either stdio (command, optional string-list args, optional string-map env) or HTTP (url, optional string-map headers). The transport can be set explicitly with type (stdio or http), or inferred from the fields provided. ${VARIABLE} references in env and headers values are substituted by environment variables.

{
  "mcpServers": {
    "local": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {"API_TOKEN": "${SOME_ENV_VAR}"}
    },
    "remote": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {"Authorization": "Bearer ${SOME_ENV_VAR}"}
    }
  }
}

/notifications

• Description: Configure optional alerts when Roksta is waiting for input or has finished its work. Preferences are saved globally in ~/.roksta.json; all notification methods are disabled by default.

• Usage: /notifications [on <bell|desktop> | off [bell|desktop] | test]

• Subcommands:

  • off: Used to turn off bell or desktop notifications, if neither are provided, all notifications are turned off.
  • on: Used to turn on bell or desktop notifications. bell or desktop must be specified. If desktop is specified, a URL will be displayed which requires the user to open it and then click on the enable button to enable desktop notifications.
  • test: Used to test if the notification system is working correctly.

If the command is used without any subcommands, the current status is displayed.

Enable bell to get Roksta to ring the terminal bell and use desktop if you would like to receive desktop notifications. desktop works by running a tiny http server in the background and events are sent to the open web page which uses the browser's ability to send notifications to the OS.

Note that notifications are sent after a short delay to ensure that the user doesn't receive notifications just as they are about to interact with Roksta.

/payment-details

• Requires login

• Description: Opens a Stripe webpage for providing or updating your payment details. By default Roksta will take a payment of $10.00 USD every time the balance drops below $2.00 USD. You can toggle the auto-payment feature and set the top-up amount and threshold in USD using the /auto-charge command. The threshold can't be less than $1.00 USD and the payment amount can't be less than $5.00 USD.

/quickstart

• Description: Opens the interactive getting-started guide.

• Usage: /quickstart

/quit

• Description: Quits the application. You can also use /exit or Ctrl+Q to quit.

/reindex

• Requires login

• Description: Updates Roksta's index on files and folders. This normally happens at the start of every goal.

• Usage: /reindex

/testing

• Description: Manage project-specific testing configuration stored under the top-level testing key in your project config file. The /testing command records two configuration values (enabled and command) in <project-root>/.rokstarc. It does NOT run the tests; it only saves the command Roksta can reference later.

• Usage: /testing <on|off|set|clear|status> ["test command"]

• Subcommands:

  • status (or no parameters): Show the current values of testing.enabled and testing.command.
  • on: Enable testing by setting testing.enabled = true and persisting the project config.
  • off: Disable testing by setting testing.enabled = false and persisting the project config.
  • set "command": Save the testing command and set testing.enabled = true. The command parameter is required and must be non-empty. Example: /testing set "pytest".
  • clear: Remove or clear the testing configuration (sets enabled = false and empties command). If no config file exists the command will clear the in-memory project config instead.

• Behaviour:

  • If no project config file exists the command will create one and initialise it with sensible defaults.
  • If the project config file contains invalid JSON, /testing will refuse to operate and will prompt you to fix .rokstarc manually.

• Examples:

  /testing status
  /testing on
  /testing off
  /testing set "jest"
  /testing clear
  

• Example workflow:

  1. Configure the project test command:

     /testing set "pytest"
     

  2. Use #test in your goal to trigger the configured test command for this run. Example goal:

     Run unit tests for the payments module and fix failures. #test
     

/redeem

• Requires login

• Description: Redeems a credit code to add credit to your account balance, shown in USD.

• Usage: /redeem <credit_code>

• Example: /redeem CreditCode123

/upgrade

• Description: Upgrades Roksta to the latest version. This command only works if Roksta was installed via pipx.

• Usage: /upgrade

/usage

• Requires login

• Description: Displays session usage and cost, developer savings and rate, and your current balance. Monetary amounts are shown in USD.

Command Line Parameters

Roksta also accepts command line parameters to allow batch execution.

• --goal: Provide a file which contains the goal that Roksta will immediately start working towards on startup. e.g. roksta --goal goal_file.txt. Ensure you include the #full-auto directive within the goal to enable it to operate in a fully automatic manner. Otherwise, Roksta will pause for user feedback.

• --exit: Instructs Roksta to exit once the goal has been completed. e.g. roksta --goal goal_file.txt --exit

• --no-index: Prevents Roksta from constructing an index for the codebase. Setting this parameter will reduce the cost of running a one-off task but will degrade performance.

• --benchmark: A useful shortcut when running Roksta within benchmarks. Equivalent to setting --full-auto --yolo --exit --no-index.

• # Directives: All goal directives, e.g. #full-auto, can also be provided as command line parameters. Just replace the # with -- on the command line. Directives that take parameters, e.g. #thinking(more) can also be used; simply provide the parameter after a space or an = sign, e.g. --thinking more or --thinking=more.

If directives are also specified within the goal, the two lists are merged to create a single list of directives that are then implemented.

Troubleshooting

• Login is mandatory: Roksta won't work if you don't log in.

• Multi-line input: Sometimes, Roksta will switch to multi-line mode, so if you can't submit your input with just Enter, try Ctrl+Enter or Ctrl+S. Note that if you use Roksta within an IDE's terminal, Ctrl+Enter might not work as IDEs sometimes capture that combination, use Ctrl+S instead. macOS users may use the Cmd key instead of Ctrl.

• Initialisation delay: The /init command may take several minutes on first run as it indexes your codebase. Please be patient during this process.

• Command not recognized: If you encounter a message stating that a command is not recognized, double-check the spelling and ensure that you are using the correct multi-line format.

Happy building and Rok on!🤘