Capri Tutorial: Control Files, Projects, and Code with a Windows AI Agent

What is Capri?

Capri is an open-source, cyberpunk-themed AI agent for Windows. It provides a native desktop interface for working with files, project folders, code, shell tools, applications, and the web through an AI assistant. Instead of writing terminal commands, you describe a goal in plain language and let Capri coordinate the work.

Capri acts as the interface and tool layer, while an external assistant supplies the AI reasoning. It supports Claude Code, Codex, and Antigravity out of the box. Other assistants can be connected through custom adapters.

Capri is an independent, unofficial fan project inspired by the cyberpunk genre and Cyberpunk: Edgerunners. It is not affiliated with or endorsed by CD PROJEKT RED, Netflix, Studio Trigger, Anthropic, OpenAI, or Google.

Key features

• Multiple AI engines: Connect Claude Code, Codex, Antigravity, or another assistant through a custom adapter.
• Native Windows interface: Use an installed desktop application instead of working directly in a terminal.
• File and project tools: Find, read, organize, and edit files or entire project folders.
• Agent workflow: Capri can plan a task, request tools, check the result, and report what happened.
• Code assistance: Ask the selected engine to write, refactor, debug, and run code.
• Approval controls: Review sensitive actions and approve or deny them before Capri changes your system.
• Configurable scope: Restrict access to selected folders and choose ask, automatic, or read-only permission behavior.

Requirements

Capri currently requires Windows 10 or newer. It is distributed as a Windows .exe installer. macOS and Linux versions appear on the project roadmap but are not currently available.

You also need your own supported AI assistant account or API key. Capri itself is open source under the MIT License, but the connected AI provider may charge for usage according to its own pricing.

Install Capri on Windows

1. Download the installer

Open the latest Capri release and download Capri-Setup.exe. Use the official repository release page rather than an unknown third-party download source.

2. Run the setup wizard

1. Open Capri-Setup.exe.
2. Follow the installation wizard.
3. After installation, open Capri from the Windows Start menu.

Because Capri is a new application that may not yet have a large download reputation, Windows SmartScreen can display a warning. If you obtained the installer from the official release page, select More info and then Run anyway to continue.

3. Connect an AI engine

On first launch, Capri asks you to select an assistant. Choose Claude Code, Codex, Antigravity, or another supported option, then sign in or provide the requested API key.

Your requests are processed by the assistant you connect. The provider's terms, privacy policy, pricing, and account rules therefore apply to that processing.

How Capri handles a task

1. You describe the goal: Enter a plain-language request in the desktop application.
2. Capri selects the engine: The request is routed to your configured AI assistant.
3. The engine creates a plan: The assistant determines which steps and tools are needed.
4. Capri presents sensitive actions: Depending on your permissions, you can review requested file or system operations.
5. You approve or deny: Approved actions are carried out through Capri's tool layer.
6. Capri reports the result: The agent checks the outcome and summarizes what it did.

Basic usage examples

Organize a folder

To clean up a folder, identify the target location and describe the desired organization:

Clean up my Downloads folder and group the files by type. Show me the plan before moving anything.

Capri can scan the folder, propose a plan, and request approval before moving files. Review destination folders and filenames carefully before accepting the operation.

Investigate and fix code

Open or grant access to the relevant project folder, then give Capri a focused request:

Find the bug in this project, explain the cause, patch it, and run the available checks.

The selected AI engine can inspect the code, locate a likely problem, edit the relevant files, and run checks. For safer review, ask Capri to explain the proposed change before allowing it to modify the project.

Summarize documents

Capri can work across multiple files in an allowed folder. For example:

Summarize every PDF in this folder and write one combined summary document.

Before approving the task, verify which folder Capri will read and where it plans to save the generated document.

Create a web project

You can also request a complete development workflow:

Set up a new web app in this folder, install its dependencies, and start it.

This kind of request can involve creating files, downloading packages, running shell commands, and launching a process. Inspect the proposed framework, commands, and target directory before approval.

Configure permissions and scope

The README provides the following example configuration:

engine: claude-code

permissions:
  mode: ask
  allowed_folders:
    - ~/Documents
    - ~/Projects

interface:
  theme: cyberpunk

The engine value selects the connected assistant. Documented values include claude-code, codex, antigravity, and custom.

The permissions section supports three documented modes:

• ask: Capri asks before acting. This is the best starting point when learning how the agent behaves.
• auto: Actions can proceed automatically. Use this only when you understand the task and have tightly restricted its scope.
• read-only: Use Capri for inspection and analysis without allowing modifications.

The allowed_folders list limits which locations the agent can access. Prefer granting access to a specific working directory rather than an entire drive or user profile.

Advanced tips

Write prompts with clear boundaries

State the target folder, desired result, validation method, and actions that require confirmation. A precise request reduces ambiguity:

Review the project in my Projects folder. Identify the cause of the failing tests, explain your proposed edits, and wait for approval before changing files. After approval, run the existing test suite.

Start in read-only mode

For an unfamiliar repository or document collection, begin with read-only access. Ask Capri to inspect the material and recommend a plan. Change the permission mode only when you are ready to authorize edits.

Use an isolated project folder

Copy experimental work into a dedicated folder and grant Capri access only to that directory. This limits accidental changes and makes it easier to review the resulting file differences.

Separate planning from execution

For large tasks, first request a plan without modifications. Review the steps, then issue a second instruction authorizing only the approved portion. This is especially useful for bulk file operations, dependency installation, or broad refactoring.

Switch engines when appropriate

Capri lets you choose among supported AI engines. If you maintain accounts for multiple assistants, select the one that best fits the current task. Remember that each provider has its own capabilities, costs, and privacy terms.

Use custom adapters carefully

Other assistants can be integrated through custom adapters. When using one, verify how it handles credentials, requests, tool calls, and returned data. The README does not provide adapter implementation instructions, so consult the project's current documentation or contribution resources before building an integration.

Do not assume every roadmap feature is available

The roadmap lists a plugin system, voice control, task scheduler, theme gallery, and macOS and Linux versions as planned rather than completed. Check the latest release notes before designing a workflow around those features.

Safety guidelines

• Review every sensitive action: Pay particular attention to deletion, movement, replacement, shell commands, and dependency installation.
• Limit folder access: Expose only the files needed for the current task.
• Keep backups: Back up important data before bulk organization, automated editing, or other large operations.
• Protect credentials: Never share API keys, account tokens, or other secrets.
• Check generated commands: Understand a shell command before allowing Capri to run it.
• Use version control: For code projects, commit or otherwise preserve the current state before requesting substantial edits.

If you discover a security issue, follow the project's security reporting instructions and report it privately.

Troubleshooting and project resources

If the installer, engine connection, or agent workflow does not behave as expected, check the Capri GitHub repository and the latest release notes. Bugs and feature ideas can be submitted through the project issue forms.

Contributions are welcome in areas such as bug reports, documentation, themes, feature proposals, and engine adapters. Review the repository's contributing guide before submitting changes.

Conclusion

Capri gives Windows users a desktop interface for directing supported AI assistants to work with files, projects, and code. Install the application, connect your preferred engine, restrict access to the folders it needs, and begin with approval-based or read-only permissions. Clear prompts, careful reviews, backups, and narrow access boundaries are essential when allowing any AI agent to act on your computer.