Documentation

Using Caliope

Caliope is an alternative to the GitHub Copilot app, for Windows. It works in your project on your own Copilot plan.

Install

You need 64-bit Windows 10 or 11, Chrome or Edge, and a GitHub Copilot plan. You don't need admin rights. Paste this line into PowerShell:

irm https://github.com/louisdegeestldg/caliope/releases/latest/download/install.ps1 | iex

It installs Caliope in %LOCALAPPDATA%\Programs\Caliope, adds it to the Start menu and opens it in Chrome or Edge as an app window. For a desktop icon, click Create shortcut in Settings → App.

• Update: click Update when Caliope says a new version is out, or run the install line again. To install new versions without asking, turn on Install updates automatically in Settings → App. Your sessions, settings and sign-in are stored separately in %LOCALAPPDATA%\Caliope, so you keep them.
• Uninstall: in Windows Settings → Apps. Your sessions stay in %LOCALAPPDATA%\Caliope until you delete that folder.
• If the install line is blocked: download Caliope-windows-x64.zip from the latest release, unzip it to a folder of your own and double-click Caliope.cmd. To update, unzip the new version into a new folder.

Sign in

Click Sign in with GitHub, enter the code it shows on github.com and authorize Caliope. It only asks to read your profile, and requests count against your own Copilot plan. If your company doesn't allow Copilot outside the editor, Caliope shows GitHub's message. If GitHub refuses with HTTP 403, your organization may have to allow Caliope as an OAuth app. GitHub Enterprise with data residency (GHE.com) isn't supported.

Modes and approvals

The mode sets what the agent may do without asking. New sessions start in Auto. Change that in Settings. Switch with Shift+Tab.

When the agent asks, press 1 to allow or 3 to deny, or type what it should do instead. A message you send from the message box also skips the question. Allow in session and Allow in project save the start of a command, such as npm test, so commands that start the same way run without asking.

Some actions always ask, except in full access, such as edits to .mcp.json, to skills, or to the .git folder. Outside Auto, edits outside the project ask too. The approval card says why.

Models and costs

• Pick the model and effort in the bar under the message box. You can switch during a session.
• New sessions start on the newest Claude Opus. Change the default in Settings → Models.
• The model picker shows what a request to each model cost you on average.
• Each project page can set a monthly limit in AI credits. From 80% sessions show a notice, and at the limit the agent stops until you raise it. The limit is checked before each request, so the request that crosses it still finishes.
• To cap spending for your whole account, set a budget for Copilot on github.com.
• When a conversation fills 90% of the model's context window, its earlier part is replaced by a summary. Claude and GPT models write that summary themselves. Change the point in Settings → Costs.

Cost compared with Copilot CLI

On a task that reads many files, Caliope used 18 to 41% fewer credits than Copilot CLI. Both read the 47 .js files in Caliope's own server/ folder, described each file in ARCHITECTURE.md and listed the three worst bugs.

• Setup: Caliope 1.0.0 in full access mode, Copilot CLI 1.0.98 with --allow-all. Both used the model in the table at low effort, with default settings otherwise. Each pair ran at the same time on two copies of the repository.
• Numbers: the median of three runs, in AI credits as Copilot reports them (1 credit is $0.01). Every run passed the check: ARCHITECTURE.md names at least 45 of the 47 files and has a Bugs heading. The quality of the descriptions was not graded.
• Short tasks: on a small change with a test, the difference was less than one credit.

Compared with the GitHub Copilot app

A browser-heavy daily check: query a cloud portal, read a BI report and a ticket tool, then write a formatted post with a screenshot in Teams.

Both ran Claude Opus 5.5 at medium effort with the same skill. Caliope in Auto mode, the Copilot app with all permissions allowed. Average of three runs each.

Working with the agent

• Plan mode. The agent researches and writes a plan without changing anything. Approve it and the build model carries it out.
• Subagents. The agent hands searches and reviews to other models, on its own or when you ask ("have GPT review this").
• Earlier sessions. Ask "what did we decide about the export?" and the agent searches the project's past sessions.
• Files and images. Type @path to attach a file, or paste and drop images. The agent reads images, PDFs and Jupyter notebooks, and edits notebook cells.
• Web. The agent searches and reads web pages. Searches go through Copilot to OpenAI at no cost, or to DuckDuckGo when that isn't available. In Ask and Accept edits mode it asks first.
• Commands. Type / for the list, such as /plan, /compact, /review and /commit.
• Undo. Rewind to one of your messages to restore the files the agent changed after it.
• Git. In a trusted folder, the Changes panel shows the diffs. Pick New worktree when you start a session to give it its own branch.
• Pull requests. Type /pr. The agent commits, pushes and opens the pull request on GitHub or Azure DevOps once you approve it. It uses the git sign-in already on your PC, so you don't need gh or az. The Pull requests page lists the open ones in your trusted projects.
• Merging. The agent merges only after you confirm, also with full access, and only once required checks, reviews and branch policies pass. You pick the merge method and whether to delete the branch.
• Scheduled tasks. Ask "check the pipeline every 10 minutes until it passes" or "remind me at 15:00". The agent comes back in the session when it's due. A loop stops at its goal or after 7 days. Recurring tasks, such as a morning check, start a new session each run. Add them on the project page. Tasks run while Caliope is open.

Projects

Each folder is a project. Its page holds settings for every session in it:

• Instructions for the agent, on top of the repository's own AGENTS.md and CLAUDE.md files and your ~/.claude/CLAUDE.md. Those files in a subfolder apply once the agent works there.
• Memory: short notes every new session starts with. The agent adds, corrects and removes notes itself. You can add one with /remember or edit them on the page.
• Hooks: run a command after the agent edits a file, such as ruff format {file}.
• Trust: the first session in a folder asks whether you trust it. Only then does Caliope load the folder's own instructions, skills, commands and MCP servers, and show its git changes (a repository's git settings can run programs).

Caliope also loads SKILL.md skills and custom slash commands in the Claude Code format, from the project and from ~/.claude.

MCP servers

MCP servers give the agent tools from other programs. The quickest way to add one is to ask the agent. It adds the server to the project's .mcp.json, and new sessions use it once you trust the folder. For a server in every project, use Settings → MCP servers. Tools that can change things ask before they run.

For Azure DevOps, enter your organization and click Add Azure DevOps. It runs with the Node.js and npx included in Caliope, so you don't need to install anything.

The agent's browser

The agent opens, reads and clicks through web pages to test what you build. It also reads a page's console and network requests to find out why it fails. Each project has its own browser profile, separate from yours, so a client's login stays in that client's project.

• Reading the open page never asks.
• Before opening a page on a new site, or clicking or typing there, the agent asks once, for the session or the project. A site is its address and port: allowing localhost:3000 doesn't allow localhost:8080.
• In Auto, pages on this PC need no approval. For other sites, a small model checks each address the agent opens and the first action on the site against your request. It asks you only when they have nothing to do with it.
• The Browser panel (the globe in a session's header) shows the session's browser live. Click, type and paste there yourself, for example to sign in. Show window brings up the real window for prompts the panel can't show, such as a Windows account picker.
• The agent is told never to type passwords.

Data and privacy

• Everything Caliope stores is on your PC in %LOCALAPPDATA%\Caliope. Your sign-in is encrypted for your Windows account.
• The app window has its own browser profile there, so extensions in your own browser can't read it. Links you click still open in your own browser.
• Your prompts and the files the agent reads go to GitHub Copilot, and to websites and MCP servers you approve. Web searches go through Copilot to OpenAI, or to DuckDuckGo.
• The agent's file tools and searches skip .env files and private keys. Add your own patterns in Settings → Permissions.
• Commands run as you: a command you allow can still read those files, and Rewind can't undo what a command did. Use version control.

Troubleshooting

For developers

Caliope is plain JavaScript on Node.js, with no dependencies.

node --use-system-ca server/main.js --open        # run from source
node --test --test-concurrency=1 "test/*.test.js"  # tests
node tools/package.mjs                             # build the release files

Legal

• Caliope is open source under the MIT license and comes without any warranty. The agent edits files and runs commands on your PC with the permissions you give it, so review what you approve.
• Caliope isn't made by, affiliated with or endorsed by GitHub, Microsoft, Anthropic, OpenAI or Google. GitHub, Copilot, Claude, GPT and Gemini are trademarks of their owners.
• You use GitHub Copilot under GitHub's terms and your own plan. Caliope calls the Copilot service directly and identifies itself to it as GitHub's Copilot CLI. GitHub documents its Copilot SDK as the way for other apps. The service isn't a public API, so GitHub can change it and Caliope may stop working.
• Caliope sends no data to its makers. It has no analytics or telemetry.