For the engineers who still want to understand the code,

Capisce is an open source tool that helps you understand a codebase.

As your agents iterate on your codebase, they also write the core business logic in pseudo-code. This pseudo-code helps you see a compressed form of your codebase, removing boilerplate.

Rust api/src/app/sessions.rs
/// Signs a person in with their name and password, and starts a session./// An unknown name and a wrong password get the same answer.pub fn login(ctx: &ApiContext, user_name: &str, password: &str) -> Result<(User, Session), ApiError> {    let now = now_seconds();    let mut db = ctx.datastore.lock();    let user = db.user_by_name(user_name).ok_or(ApiError::InvalidCredentials)?;    if let Some(until) = user.locked_until {        if until > now {            return Err(ApiError::AccountLocked { until });        }    }    if user.password_digest != password_digest(user_name, password) {        let failed = db.user_record_failed_login(&user.id);        if failed >= MAX_FAILED_LOGINS {            db.user_lock_until(&user.id, now + LOCK_SECONDS);        }        return Err(ApiError::InvalidCredentials);    }    db.user_clear_failed_logins(&user.id);    let session = db.session_insert(&user.id, now + SESSION_SECONDS);    Ok((user, session))}
Capisce sessions.login
def login(user_name, password):    with store_lock:        user = user_store.user_by_name(user_name)        if user is None:            raise ApiError.InvalidCredentials      # 401        if user.locked_until is in the future:            raise ApiError.AccountLocked           # 403        if the password does not match:            failed = user_store.user_record_failed_login(user)            if failed >= 5:                user_store.user_lock_until(user, now + 15 min)            raise ApiError.InvalidCredentials      # 401        user_store.user_clear_failed_logins(user)        session = user_store.session_insert(user, now + 8 h)        return user, session

Zooming in, zooming out

Capisce helps you understand a codebase at different levels of resolution.

We start at your high-level domains.

The domains of the Oxide-lite example on one canvas: Console, Access, Projects, Instances and Disks, inside the Rack, with arrows for how they relate.

Clicking on a domain opens up the core user stories within that domain.

Clicking the Instances domain opens its page, with its flows “Creating an instance from the console” and “Stopping an instance”, its relations and its models.

Clicking a user story shows us a diagram that traces through the entire program. We also see pseudo-code of the high-level user story.

Clicking the flow “Creating an instance from the console” opens a trace diagram across the console and the API beside the flow’s steps in plain words.

We can click a step in the flow diagram and see the code at that level.

Clicking steps of the trace diagram one after another shows the pseudo-code of the function each step happens in.

The pseudo-code is derived directly from the actual code, which we can toggle in the upper right.

The </> button in the upper right of the code swaps the pseudo-code of create_instance for its real Rust code, and back.

Comments

This surface is interactive. You can leave your agents notes by highlighting…

Highlighting the name “new” in the pseudo-code shows a Comment button; the comment asks to rename it so it is clearer.

… or by using the comment box (toggleable by c).

Pressing c turns on comments: a click drops a pin and opens a note, and a drag draws a circle around a step of the trace.

Diffs

Capisce’s pseudo-code is saved alongside your codebase in a .capisce/ folder. This allows Capisce to show you a diff of your feature branch against main.

The Changes page of a feature branch lists the changed endpoint and function; opening the function shows its added and removed pseudo-code lines and a new step in the trace.

Glossary

You can keep definitions of common domain models in Capisce.

Clicking the term store_lock in the pseudo-code shows its definition: the API keeps everything in memory behind one lock.

Skills

Capisce includes skills so that your agents will automatically maintain the pseudo-code reflection of your codebase.

npx skills add kierangilliam/capisce

Examples

Oxide-lite: This is meant to be a replication of Oxide’s Rust control plane interacting with a TypeScript frontend. I say “meant to be” because I gave boot to an agent to transpose Oxide’s codebase into this simplified form, but I will not pretend to be smart enough to claim it’s entirely correct. All that to say, any crimes against Oxide’s good taste or architectural intent were committed by the agent. I maintain plausible deniability. (code) (demo)

Help desk: A help desk built in Go. (code) (demo)