Everything CPOS does, and how.

Overview#

CPOS is three local clients that share the same files and talk to each other over 127.0.0.1. There are no accounts, no external servers, and no tracking — your code, your judge sessions, and your progress data never leave your machine.

Install all three for the full experience. The browser companion is required for capture and submit; the VS Code extension and the terminal app can each work alone on top of it, or together — they stay in sync automatically.

How CPOS works#

The core loop is capture → code → run → submit. Here is the whole flow from opening a problem to seeing your verdict:

1. Pick your folder

   Open any folder in VS Code, or let the terminal app use ~/cpos. This is where solution files will be created.

2. Open a problem in your browser

   Any Codeforces, CSES, or AtCoder problem page. Log in first if you plan to submit later.

3. CPOS captures it

   The companion's content script reads the public sample inputs and outputs (and the full statement) from the page and POSTs them to CPOS on your machine.

4. A file appears

   For example 1971D.cpp, created from your template with the sample tests attached in the panel.

5. Write your solution

   In VS Code, in the in-browser editor, or in a terminal editor launched from the TUI.

6. Run samples

   Run All in the panel or T in the terminal — CPOS compiles locally and diffs each sample's output.

7. Submit

   CPOS queues your code and the companion autofills the judge's submit form in your existing logged-in tab, picking the newest matching compiler.

The three clients on one machine

Why submit works the way it does

CPOS deliberately does not post solutions to the judges over HTTP. That approach fights anti-bot protection and fragile session handling. Instead, the editor queues the submission locally, and the companion autofills the real submit form in your own logged-in tab and activates the submit control — the same thing you would do by hand, minus the copy-paste:

The injected script runs in the page main world (required to reach the source textarea), sets the hidden source field, language, and problem identifier, and carefully avoids change events that would reset the judge's Ace editor and wipe your code. The companion picks the newest matching compiler in the dropdown — G++23 before G++17.

Installation#

Three installs, roughly two minutes. Package-manager installs use prebuilt binaries from GitHub Releases — you do not need Rust, Cargo, or a C++ linker to run CPOS itself.

1 · Terminal app

macOS / Linux — Homebrew

brew tap Soham109/cpos https://github.com/Soham109/cpos
brew install cpos
cpos

Windows — Scoop

scoop bucket add cpos https://github.com/Soham109/cpos
scoop install cpos
cpos

No package manager? Installer scripts

curl -fsSL https://raw.githubusercontent.com/Soham109/cpos/main/install.sh | sh

irm https://raw.githubusercontent.com/Soham109/cpos/main/install.ps1 | iex

The Unix script installs to ~/.local/bin/cpos (add it to your PATH if needed); the Windows script installs under %LOCALAPPDATA%\Programs\CPOS\bin and updates your user PATH. Pin a version with CPOS_VERSION=0.2.2 before the command.

Manual download

Grab the asset from the latest GitHub Release and put cpos on your PATH. Building from source is also possible with cargo install --git https://github.com/Soham109/cpos (requires a Rust toolchain).

2 · VS Code extension

Install CPOS from the VS Code Marketplace, or search "CPOS" in the Extensions view. It updates automatically from the Marketplace.

3 · Browser companion

Chrome / Edge / Brave — install from the Chrome Web Store. Updates are automatic.

Firefox — a source install for now (AMO publishing is planned):

1. Clone the repo: git clone https://github.com/Soham109/cpos
2. Open about:debugging#/runtime/this-firefox
3. Click Load Temporary Add-on… and select extensions/firefox/manifest.json

Quick start#

First run: the setup wizard

The first time you launch cpos, a 4-step wizard runs:

1. Handle

   Type your Codeforces handle — it drives sync, analytics, and recommendations.

2. Language

   Pick your default language with ←/→.

3. Template

   Copy your solution template and press v to paste it whole (multi-line formatting preserved), or press Tab to switch to Upload and load it from a file path. Leave blank for the built-in template.

4. CSES (optional)

   Press o to open the CSES login and paste your PHPSESSID cookie to sync solved problems — or skip and set it later in Config.

Re-run the wizard any time by clearing your handle in config.toml.

Your first problem, end to end

1. Open a folder in VS Code

   CPOS creates solution files here. (Skipping VS Code? The TUI uses ~/cpos.)

2. Visit a problem page

   Say Codeforces 1971D. The companion badge confirms the capture; 1971D.cpp appears with samples loaded in the CPOS panel.

3. Solve, then Run All

   Every sample compiles and runs locally with a per-test diff. T does the same in the terminal.

4. Submit

   Press Submit in the panel (or s in the TUI). Your browser opens the judge's submit page, the form fills itself, and off it goes.

Terminal app#

The TUI is a full practice cockpit: browse the catalog, sync your rating, track contests, read statements, run samples, and get recommendations — without opening a judge tab. Keep it running while you code in VS Code; both see the same captures, submits, and progress.

Keys

On the Practice tab

Statement view

Press v on the Problems tab for the full in-TUI problem view: title, limits, sections, lists, code, terminal-rendered LaTeX, and captured diagrams, with sample I/O inserted exactly where the VS Code Statement tab shows them. Samples use linked Codeforces block shading when available and switch between side-by-side and stacked layouts with terminal width. Kitty, Sixel, and iTerm2 graphics are detected automatically; other terminals get a colored Unicode half-block rendering. From the statement, T runs the samples and b opens the original page.

Using your own editor

Set editor in config.toml to commands like nvim {file}, hx {file}, or emacs -nw {file}. CPOS suspends the full-screen TUI while the editor runs and restores the dashboard when it exits — no flicker, no corrupted screen.

Sync

A background task fetches Codeforces API data — problems, submissions, rating, contests — into a local SQLite cache; analytics and recommendations read from that cache. Press r to refresh. CSES progress arrives from the browser companion, or from a configured cses_session cookie.

VS Code extension#

Write code in the editor; the CPOS panel handles everything around it.

• Tests / Statement / Solution tabs — samples, the captured statement rendered natively with MathJax, and a Solution tab with video solutions (clickable YouTube thumbnails) plus one-click editorial and search links
• Run All — compile and test every sample locally, with per-test output diffs
• Submit — queue the solution for the browser companion; if the companion isn't ready, CPOS offers an Open submit page fallback
• Test cases — edit samples freely; multi-case inputs show linked input/output blocks when captured from Codeforces, and boxes auto-size to their content
• Visualize — open the sample visualizer for the active problem via CPOS: Visualize Samples
• Settings gear — configure the default language and shared per-language templates used by VS Code, the terminal app, and the browser editor alike
• Header links — Sponsor, Theme, Discord, and GitHub stay reachable at any sidebar width, collapsing to icons by priority as it narrows

Settings

Command Palette: CPOS: Run Samples, CPOS: Submit Active File, CPOS: Open Problem, CPOS: Visualize Samples, and CPOS: Start/Stop Capture Server; Run and Submit also appear as editor-title buttons.

Panel themes

Browser companion#

The core is capture and submit for Codeforces, CSES, and AtCoder. On top of that sits an optional layer of practice and on-page tooling for Codeforces and CSES — everything read-only (public CF API + localhost), and every feature toggles individually from the popup. The popup itself has three tabs: Settings (feature switches, appearance with theme swatches and a custom accent color picker, shared code templates), Recommend, and Compete.

In-browser editor

A CodeMirror editor on problem pages: run against the samples with per-test diffs and custom stdin, current-line highlight, bracket matching, find & replace, a zen layout, and multiple color schemes. Run (Ctrl/⌘+Enter) toggles to Stop for cancellable runs; results land in a resizable console with a pass-ratio meter, per-test cards, jump-to-first-failure, and a copyable summary. Submit is Ctrl/⌘+Shift+Enter. Running compiles locally, so it needs CPOS on 127.0.0.1 (the VS Code extension or the terminal app) — editing works on its own.

Recommend tab

The popup's Recommend tab is a front-end for the central practice engine: pick one of the seven modes, autocomplete tags, set a rating range, freshness floor, and count, and get tier-colored recommendations with contest year, tags, and the engine's reasons — plus your level, goal, readiness, and weak-tag chips. It requires the terminal app running (only the TUI holds the submission cache).

Compete — 1v1 races

Challenge a friend by Codeforces handle or publish an open race others can discover and accept within a chosen rating range. Pick a specific problem or a rating, set a time limit, and CPOS referees from public submissions — the first Accepted after the start wins. In-page cards let you accept or decline a challenge right on Codeforces, and the on-problem sword icon shows a live race state. Delivery uses public ntfy.sh topics derived from CF handles; messages carry only race metadata — never code, cookies, or passwords. VS Code mirrors races, results, and matching preferences over the localhost /challenges endpoint, so you can manage races from either side.

Practice tools

• Profile analytics — activity heatmap, streaks, solved-by-rating and by-index histograms, top tags, verdict & language donuts, a when-you-code punch-card (hour × weekday), tag-strength radar, difficulty trend, solved-per-month, and insight facts like first-attempt accept rate and peak coding hour
• Profile compare — side-by-side stats with a rating-history overlay for any handles
• Daily problem & streak — a deterministic problem of the day, tuned to your rating automatically or pinned to an exact rating from the popup
• Favorites & problem timer — star problems for the popup; a draggable per-problem stopwatch that persists
• Shared templates — a per-language templates card (upload / reset / save & sync); edits made while CPOS is offline queue up and sync when a runner reconnects

On the page

• Rating predictions on contest standings and contest reminders with a configurable lead time
• Problem tools — rating badge, tag-hider / training mode, one-click sample copy, and similar-problem links
• Problem focus — an always-available toggle on Codeforces problem pages that hides the right rail and widens the statement for split-screen solving
• Problemset & standings tools — solve-status row coloring, hide-solved, per-problem submission counts, language colorizing, friends-only filter
• Pen & marker — freehand annotation and statement highlighting, saved per problem page and anchored to the content as it scrolls
• Appearance — syntax highlighting in statements, site themes, and a flat "Modernize" restyle that composes with them

Sample visualizer#

CPOS can look at a raw sample input and draw what it is. It auto-detects the structure — graphs and trees (force and tidy layouts, edge weights, re-rooting, colored node values, marked vertices), parent arrays, grids and mazes, value-heatmap matrices, arrays, permutations with cycle arcs, intervals, 2D point sets, strings (bracket sequences get matched-pair arcs and nesting-depth colors), multi-string inputs, and functional graphs — and renders it interactively with pan, zoom, and drag.

• In the browser — a ◈ VIZ slide-in panel on Codeforces, CSES, and AtCoder problem pages; toggle it with the "Sample visualizer" switch in the popup
• In VS Code — the CPOS: Visualize Samples command opens a visualizer tab for the active solution's samples; an optional panel button is gated behind cpos.showVisualizeButton
• Controls — per-testcase selector for multi-case inputs, input vs expected-output views, manual type and indexing overrides, live-editable input, and SVG / Graphviz DOT export

Execution trace player

The visualizer can also run your own code on the shown sample through the local CPOS runner and animate the execution on the drawing — zero setup. Python runs under a line tracer that narrates variable, list, and matrix changes; C++ sources are instrumented for array/matrix/scalar assignments and loop-variable tracking before compiling (with a silent fallback to your original source if instrumentation fails). You get a live variables panel, an execution cursor, index pointers under the cells and nodes your variables reference, and keyboard scrubbing (arrows to step, space to play, r to run). For full control, optional #cpos visit u / #cpos set i v / #cpos cell r c v / #cpos edge u v stderr macros drive the animation manually. A freehand marker (three ink colors) survives pan/zoom and is included in SVG exports.

Practice engine#

The central practice engine (src/engine/practice.rs) turns your full submission history into a per-tag skill model, then scores every unsolved problem against it. One engine drives three surfaces: the TUI's Practice tab, the browser popup's Recommend tab, and the GET /recommend localhost API. Every recommendation carries human-readable reasons — e.g. "weak topic trees: your skill ≈1000 vs level 1300 · 2024 contest" — so you always know why a problem was picked.

The skill model

Every accepted problem contributes a (rating, weight) sample to each of its tags. The weight rewards recent, clean solves:

weight = decay × clean
decay  = 0.5 ^ (days_since_solve / 240)     # 240-day half-life, floored at 0.05
clean  = 1 / (1 + 0.3 × wrong_attempts)     # 1 WA ≈ ×0.77, 4 WA ≈ ×0.45

A tag's skill is the weighted 75th percentile of those sample ratings, and your overall level is the same percentile across everything you've solved, floored by your official CF rating (whichever is higher; 1200 if there's no data). Tags you have attempted but never solved are tracked as explicit weaknesses at level − 300. A tag is flagged weak when it's unsolved, its skill trails your level by more than 150, or the evidence is thin despite failed attempts.

Candidate filters

Only unsolved, rated problems survive. Optional tag include/exclude lists and a hard contest-year floor apply next. Without an explicit rating range, the band runs from a mode-dependent floor (level −200 for most modes, −250 for refresh, −400 for explore, none for upsolve) up to level +700. Contest years missing from the cache are estimated by regression over known contest ids, so the freshness filter works across the whole problemset.

Scoring signals

The top scorers are then diversified: at most max(count/4, 2) picks may share a primary tag or a 100-point rating band, so the list is never fifteen identical DP problems. With no history at all (cold start), scoring biases toward popular problems near rating 1200 until your submissions fill the model in.

Seven query modes

Goal plans (plan mode)

Set a goal — CF rank milestones or an exact rating (900–3500) — and the engine builds a curriculum against a 33-topic map of which tags start to matter at which rating (implementation at 900 … flows at 2300):

• Readiness % — every in-scope topic is scored Ready (1.0), Developing (0.6), Gap (0.25), or Untouched (0.0), weighted by how relevant it is to the goal rating, and averaged. Labels come from solves at level: 3+ at-level solves → Ready, 1–2 → Developing, none at level → Gap, none ever → Untouched.
• Rating rungs — unsolved problems on 100-point rungs from your level to the goal (at most the 5 rungs nearest it), staged Base → Build → Push → Target, weak and uncovered topics front-loaded, max two problems per topic per rung.
• Start anywhere — press Enter on a step in the TUI to jump into the normal solve flow.

Using the engine

TUI — the Practice tab (keys above). Browser — the popup's Recommend tab queries the same engine with mode, tag autocomplete, rating range, freshness, and count; it needs the terminal app running, since only the TUI holds the submission cache. API — query it yourself:

curl 'http://127.0.0.1:27121/recommend?mode=weakness&count=10'

The response contains a summary (level, official rating, goal, readiness %, weak and strong tags) and the scored recommendations, each with its reasons and contest year.

Architecture & protocol#

Both CPOS applications expose a small HTTP API bound to the loopback interface. The companion polls both ports; cross-origin headers are permissive because traffic never leaves the machine.

Where files live

The interactive architecture graph

For the full picture, open the interactive architecture graph — a navigable knowledge graph of the entire codebase: 4,484 nodes and 11,100 edges across 174 detected communities, covering a 206-file corpus at 100% extraction. Communities map onto the real subsystems (TUI event loop, capture server, SQLite cache layer, the recommender engine, the popup hub, the self-update engine, …), each node links to its source file, and search works across everything. It's generated from the code by tools/build_graph.py and served as one compact data file, so it stays in sync with the repository and adds no runtime dependency.

Configuration#

Terminal app — config.toml

default_language = "cpp"
theme = "purple"   # purple | cyan | green | amber | mono | plain | light
editor = "code {file}"

[handles]
codeforces = "your_handle"

plain is a neutral grayscale theme for low-color terminals; mono is the single-accent minimal one; light suits light terminal setups. Set workspace_dir to change where the TUI creates solution files, and cses_session to sync CSES progress server-side.

Shared per-language templates live in the config directory and are served over /config to VS Code and the browser editor — edit them once, they apply everywhere.

Environment

Updating#

On startup the terminal app does a quick, best-effort update check. If it's outdated, CPOS asks before updating — never silently. Offline or slow? CPOS just opens normally.

cpos update

• Terminal app — cpos update delegates to Homebrew or Scoop for package installs, and refreshes standalone Unix binaries in place. Config, cache, templates, and problem data are kept.
• VS Code extension — updates automatically from the Marketplace.
• Browser companion — Chrome/Edge/Brave update from the Web Store automatically. Firefox source installs: pull the latest repo and reload extensions/firefox/manifest.json.

Troubleshooting#

The issues people actually hit, with the fast fix. The full guide with every known case lives in TROUBLESHOOTING.md.

Run All fails with spawn sh ENOENT

CPOS couldn't start a shell — this is not a verdict on your solution. Update the VS Code extension to 0.3.21+. On macOS, install a compiler (brew install gcc) and launch VS Code from the terminal (code .) so PATH includes Homebrew. On Windows, install a C++ toolchain (e.g. MSYS2's mingw-w64-ucrt-x86_64-gcc) and put it on PATH. View → Output → CPOS shows the exact command that ran.

#include <bits/stdc++.h> not found on macOS

Apple's g++ is Clang. brew install gcc — CPOS auto-detects the Homebrew GNU compiler.

Submit does nothing

1. Companion installed and enabled in Chrome/Edge/Brave (or Firefox source install)?
2. Logged in to the judge in that same browser profile?
3. VS Code extension running (it owns the capture server on 27122)?
4. Still stuck — the panel offers an Open submit page fallback on 0.3.30+.

Samples or file not appearing

1. Open the folder you want files in before capturing.
2. Only one VS Code window can own port 27122 — the panel warns if another window is active.
3. Refresh the problem page after installing the extension.

Windows: source build fails with link.exe not found

Only applies to cargo install builds — the prebuilt installers avoid it entirely. Install Visual Studio Build Tools with "Desktop development with C++", or switch Rust to the GNU toolchain with MSYS2.

TUI shows garbled text on Windows

Fixed in 0.1.6+ — CPOS switches the console to UTF-8 on startup. Run cpos update.

Community#

CPOS is built by one person, in the open, MIT-licensed. The Discord is the best place for help, workflows, and what's coming next; GitHub issues for bugs and feature requests. If CPOS saves you time on every problem, sponsoring funds new judges, contest mode, and ongoing maintenance.

Roadmap highlights: AtCoder in the terminal app (capture, submit, and the visualizer already work in the browser and VS Code), CodeChef support, contest mode with per-problem timers, and reading submission verdicts back into CPOS.