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.
def create_instance(caller, project_name, new): with store_lock: # Find the project; collaborators and admins project, _ = project_roles.authorize_project( caller, project_name, "collaborator") # Check the name and the sizes names.validate_name(new.name) if not (1 <= new.ncpus <= 8 and 1 <= new.memory_gib <= 32 and 10 <= new.boot_disk_size_gib <= 200): raise ApiError.InvalidRequest # 400 # Refuse a name already used in the project if instance_store.instance_by_name(project, new.name): raise ApiError.InstanceNameTaken # 409 # the boot disk is named "<instance name>-boot" if disk_store.disk_by_name(project, boot_disk_name): raise ApiError.DiskNameTaken # 409 # Check the project's quota quotas.check_quota(project, new.ncpus, new.memory_gib, new.boot_disk_size_gib) # Take an address from the pool address = rack_store.address_allocate(instance_id) if address is None: raise ApiError.AddressPoolExhausted # 503 # Create the boot disk, attached boot_disk = disk_store.disk_insert( project, boot_disk_name, new.boot_disk_size_gib, instance_id) # Record the instance as creating instance = Instance(new, project, boot_disk, address, state: "creating", state_changed_at: now) instance_store.instance_insert(instance) return instance/// Creates an instance with its boot disk and an address. It is recorded as creating, and gets a/// place on the rack a few seconds later.pub fn create_instance( ctx: &ApiContext, caller: &User, project_name: &str, new: NewInstance,) -> Result<Instance, ApiError> { let mut db = ctx.datastore.lock(); let (project, _) = authorize_project(&db, caller, project_name, ProjectRole::Collaborator)?; validate_name(&new.name)?; if new.ncpus < 1 || new.ncpus > MAX_CPUS { return Err(ApiError::InvalidRequest(format!("an instance has 1 to {MAX_CPUS} CPUs"))); } if new.memory_gib < 1 || new.memory_gib > MAX_MEMORY_GIB { return Err(ApiError::InvalidRequest(format!("an instance has 1 to {MAX_MEMORY_GIB} GiB of memory"))); } if new.boot_disk_size_gib < MIN_BOOT_DISK_GIB || new.boot_disk_size_gib > MAX_BOOT_DISK_GIB { return Err(ApiError::InvalidRequest(format!( "a boot disk is {MIN_BOOT_DISK_GIB} to {MAX_BOOT_DISK_GIB} GiB" ))); } if db.instance_by_name(&project.id, &new.name).is_some() { return Err(ApiError::InstanceNameTaken); } let boot_disk_name = format!("{}-boot", new.name); if db.disk_by_name(&project.id, &boot_disk_name).is_some() { return Err(ApiError::DiskNameTaken); } check_quota(&db, &project, new.ncpus, new.memory_gib, new.boot_disk_size_gib)?; let instance_id = db.next_id("instance"); let address_ip = db.address_allocate(&instance_id).ok_or(ApiError::AddressPoolExhausted)?; let boot_disk = db.disk_insert(&project.id, &boot_disk_name, new.boot_disk_size_gib, Some(&instance_id)); let instance = Instance { id: instance_id, project_id: project.id, name: new.name, ncpus: new.ncpus, memory_gib: new.memory_gib, state: InstanceState::Creating, state_changed_at: now_seconds(), boot_disk_id: boot_disk.id, address_ip, failure_reason: None, }; db.instance_insert(instance.clone()); Ok(instance)}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 example cloud console 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
/capisce:setupThis builds Capisce’s state on a new codebase. To be used once during setup./capisce:updateThis updates Capisce’s state by writing pseudo-code and updating the glossary for new code changes./capisce:address-commentsAn agent will pull your comments and address them, either replying to your comment or making a change to your codebase.
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)