Documentation

How to use Shipcode

Everything you need to pick a project, prepare it on your computer, and move forward with the CLI, guides, and mentor. First time here? Read it top to bottom. Already building? Use the index.

Last updated: September 2026

How Shipcode works

There are no exercises and no editor in the browser. You build a real program on your own computer, in your own editor, in your own language.

Every project is split into stages, grouped into phases. A stage asks your program for one concrete capability — that it starts up, that it understands a token, that it survives an edge case — and comes with two things: a prose guide explaining why, and the contract your program has to meet.

Guides never contain the solution. They explain the problem, the input and output format, and the order worth attacking it in. You write the code.

Project
A complete program you build from scratch: a shell, a JSON parser, an HTTP server.
Phase
A group of stages with a meaningful goal: “make it run”, “make it survive edge cases”.
Stage
The smallest step: one guide, one contract, its tests.
Attempt
Your implementation of a project in one language and one content language. Your progress lives here.

Your code lives on your computer and belongs to you. Shipcode stores how far you got, not what you wrote.

Finding a project

The catalog lives under Challenges in the top navigation. You do not need an account to explore it.

Search understands names, concepts and languages: “parser”, “sockets” and “rust” take you to different places. Press / anywhere on the page to jump to the search box without reaching for the mouse.

If you do not know what to search for yet, Project Match asks about your goal, language, level, and available time. It returns three projects and explains every match; your answers live in the URL and are not saved to your profile.

Filters live on the left. You can tick several values in one group (Python and Go) and combine groups with each other (Python, beginner difficulty and fewer stages). Above the results there is a chip per active filter: remove them one by one or use “Clear all”. On small screens filters sit behind the Filters button, which shows how many you have on.

Availability
Separates what you can start today from what is still being written.
Category
The area: systems, networking, databases, languages, tooling, concurrency, graphics or security.
Difficulty
From beginner to expert. It measures the project, not your experience with the language.
Language
The languages this project is already prepared for.
Concepts
What you will practice: “fork”, “parsing”, “wal”…

The default order is Relevance; you can also sort by Most popular, Newest, Easiest first, Hardest first and Shortest.

Your whole search lives in the URL. You can share it, bookmark it, and use the browser's back button without losing your filters.

A project marked “Coming soon” has its syllabus closed and its phases defined, but we are still writing its guides. You can open it and read the roadmap; starting it, not yet.

Reading a project page

Before you commit to a project, its page tells you exactly what you are getting into.

At a glance
Difficulty, estimated time, number of stages and category.
Before you start
What you will build, what you will learn, why it is worth it, and what you should know beforehand.
Roadmap
Every phase with its stages, in order. The full syllabus, no surprises.
Suggested languages
The languages this project is prepared for. Pick one here and the rest of the page adapts.
Guide language
The languages this project's guides are fully translated into.
Your progress
When signed in: how far you got, and the button to pick up where you left off.

The language and syllabus pickers on this page do not create anything: they just prefill the start form. Choosing here saves you two clicks later.

Starting a project

From the project page, “Start this challenge” takes you to a short form. You need an account: if you are not signed in we send you to log in and bring you straight back to this form, with what you had already chosen.

  1. Pick the language

    Only the languages this project is prepared for. The tester treats your program as a black box: it does not read your code, it checks that it behaves.

  2. Pick the guide language

    Only languages with a complete translation. This is independent from the interface language: you can read Shipcode in English and the syllabus in Spanish.

  3. Tell us how comfortable you are with that language

    This is not the project's difficulty, it is your experience. We use it to calibrate how many hints to give you.

  4. Pick how much time you want to spend

    We turn it into how many weeks it would take you at that pace. It is an estimate to orient you, not a contract.

  5. Tell us why you are building it

    Fundamentals, portfolio, interviews or curiosity. It prioritizes the examples and next steps you get shown.

  6. Pick your operating system

    So we can tailor the project instructions. On Windows the supported path is WSL.

  7. Paste your repository, if you already have one

    Optional. It keeps a pointer to where you are building; it is not published on your profile.

Submitting creates the attempt in your account and takes you to its setup page. It appears under Projects in progress immediately, but Continue returns to setup until the CLI finishes creating the local directory.

The combination of project, language and guide language is what defines your attempt. Starting the same project in another programming language — or another guide language — creates a separate attempt with its own progress; both move forward without colliding.

If you start a combination you already have active, nothing new is created: you resume the attempt you already had.

Install the Shipcode CLI

Install the shipcode command before running the setup command shown on your project page. One installer detects your computer, verifies the download, and places the binary in ~/.local/bin.

  1. Run the installer

    Use the same command on Linux, macOS, and inside WSL on Windows. It detects x64 or ARM64 automatically and verifies the archive's SHA-256 checksum before installing it.

  2. Make the command available

    If your terminal cannot find shipcode afterward, add ~/.local/bin to your PATH and open a new terminal: export PATH="$HOME/.local/bin:$PATH". Confirm it with shipcode --version.

Linux, macOS, and WSL

curl -fsSL https://shipcode.withdiego.dev/install.sh | sh

The links always point to the latest stable release. To update later, run `shipcode update`. To use a fixed version or inspect every file, open the public shipitcodes/cli releases page on GitHub.

The same installer updates an existing installation. You can also run shipcode update: it downloads the latest stable version, verifies its checksum, and replaces the binary.

The CLI supports Linux x64 and ARM64, macOS Intel and Apple Silicon. On Windows, use WSL; there is no native binary yet.

Connect the CLI to your account

The init, test, and submit commands need a CLI session. Sign-in is authorized in the browser without exposing the long-lived credential to you.

  1. Open the one-time link

    The CLI prints a URL. Open it, sign in to Shipcode if needed, and confirm the terminal shown on the page.

  2. Paste the short code

    The website shows an SC-… code that expires after 10 minutes and works only once. Paste it into the prompt still waiting in your terminal.

  3. Manage your terminals

    Every authorized terminal appears under Settings → CLI sessions, with its creation date and latest use. Revoke any of them and it will need to sign in again.

Sign in from your terminal

shipcode login

Once connected, install Git and return to setup. Run shipcode init sc_init_… from the folder where you want the project. The CLI downloads the pinned starter, verifies its SHA-256, creates the Git repository, and never overwrites a destination with content.

Inside the generated directory, shipcode test sends a bounded project snapshot to the private sandbox and runs the current required stage there. shipcode submit tests it again in the cloud, creates a local commit, records the verified result, and opens the next stage. Both commands accept --dir to target another directory.

For automation, SHIPCODE_TOKEN temporarily overrides the saved session. Treat it like a password: never share it or commit it to a repository.

Reading guides and moving through stages

Each stage is a page with its guide. The stage index sits on the right, and links to the previous and next stage at the bottom.

Progress is sequential and cannot be skipped: a stage opens once you have closed every mandatory stage before it. Optional stages never block, and a stage you already completed can always be redone.

Even so, no guide hides text from you. You can read a stage that is ahead of where you are: it renders in full, marked read-only, and we tell you which stage you need to close for it to count. Reading it does not move your progress or knock you off where you were.

You're previewing this guide
Not signed in, or you have not started the project. It reads in full, but nothing is recorded.
Active stage
You are inside the frontier. This is the stage you continue from when you come back.
Read-only mode
The stage is ahead of where you are. You can read it, but it does not count yet.

Run shipcode test from your project to verify the current stage in the private sandbox. When it passes, shipcode submit runs it again, records the verified result, and advances your progress.

Your progress and your projects

Projects in progress holds everything you started. Each card is an attempt, not a project: the same challenge in Python and in Java are two cards.

Each card shows the language, the content language, how many stages you have closed and when you last worked on it. If you have not run shipcode init yet, “Initialize project” takes you back to that command. After that, “Continue” drops you on the stage you were on.

Your progress also appears summarized on each project's page, next to any other attempts you have of that same challenge.

With Pro, you can enable an optional public profile at /u/your-username to show projects in progress and completed. Your repository URL is never published there.

Asking the project mentor for help

The mentor is a Pro capability inside every active stage. It is built to help you reason and debug, not to write the project for you.

Context
It receives the stage guide and public test contract, your language, operating system, experience, goal, and aggregate run state. It also remembers the six latest exchanges in that stage.
Teaching boundaries
It responds with mental models, diagnostic questions, hints, and small experiments. It must not provide complete implementations; any code block starts collapsed.
Privacy
The CLI sends a bounded text snapshot on submit or when a test fails; common secrets, ignored files and binaries are excluded. Shipcode does not access your computer on its own or send your repository or user ID to Gemini.
Availability
It only chats about an attempt you own and a stage inside your current frontier. It stays locked on a future guide so it cannot skip the learning path.

A failed question does not consume usage. If Gemini does not respond, you can try again.

Interface language vs. guide language

These are two different things, and it is the most common confusion. You can run Shipcode in English while building a project whose guides you read in Spanish.

Interface language
Buttons, menus and messages. Change it from the footer selector or from Settings; it applies to the whole site.
Guide language
The guides of the project you are building. Chosen when you start, and fixed for that attempt: changing the interface does not move it. On your project cards it is labelled Content language.

The start form only offers languages this project is fully translated into, because starting in one language and hitting guides in another halfway through would make no sense.

In the catalog the rule is looser: a project that is not translated into your language yet still shows up, in its original language, instead of vanishing from the results.

Want the same project in another language? Start it again choosing that language. It is a separate attempt and you keep both.

Your account and your profile

You can browse the catalog and read guides without an account. You need one to start a project and to have your progress saved.

You can sign up with your email or with GitHub. If you sign up with email we send you a confirmation link; open it on the same computer and you come back to where you were. If it does not arrive, you can ask us to resend it.

Settings is where you manage your display name and username, Pro profile visibility, password recovery, interface language, CLI sessions, mentor usage, and billing.

Profile
Your name and your username. Your picture comes from the account you sign in with.
Account
The email we identify you by. For now it cannot be changed on your own.
Password
It is reset securely through a link sent to your account email. You can also request one from the sign-in screen.

Plans, mentor usage, and billing

Published content, starters, the CLI, and saved progress are part of Free. Tests run exclusively in Pro's private sandbox; Pro costs $8 USD a month and also includes the contextual mentor and the option to publish your profile.

Included allowance
Pro includes a generous mentor allowance that resets with your real billing period. Settings shows the percentage remaining and the renewal date.
Extra credits
Once the allowance runs out, you can add credits starting at $5 USD. They are only used after included usage, the balance expiring first is consumed first, and every top-up expires one year after purchase.
Subscription
Stripe handles payment, invoices, and cancellation. The customer portal lets you manage the subscription; after canceling, you keep Pro through the end of the paid period.

A Checkout confirmation never grants access by itself. The screen may take a few seconds to update while Shipcode receives and verifies Stripe's signed webhook.

Frequently asked questions

Can I build it in any language I want?
The tester treats your program as a black box, so technically any language works. The start form only offers the ones that already have guides and install commands ready for that project.
Can I skip a stage?
No. You can read ahead in read-only mode, but it does not count until you close the mandatory stages before it. Optional stages never block anyone.
Can I carry the same project in two languages?
Yes. They are independent attempts, each with its own progress, and they show up as separate cards.
What happens if I hit start again?
If it is the same project, programming language and guide language, you resume the attempt you already had. Nothing is duplicated and nothing is erased.
Where does my code live?
On your computer. Shipcode neither hosts nor runs it: it stores how far you got and, if you pasted it, your repository URL.
Can the mentor see my code?
It can review the bounded text snapshot sent by the CLI on submit or when a test fails. It does not access your computer or repository on its own, and common secrets, ignored files and binaries are excluded.
What happens if I revoke a CLI session?
That terminal can no longer initialize, test, or submit projects. Your project and progress stay intact; run shipcode login again to authorize a new session.
Can I stop and come back in a month?
Yes. Progress is saved per attempt and does not expire. Go back to Projects in progress and continue where you were.
What does “Coming soon” mean?
The syllabus is closed and the phases are defined, but the guides and tests are still being written. You can open the project to review its roadmap and explore projects that are already available.