Medical school requires a sturdy one study workflow. I struggled for a year trying to find the best tools to maximise efficiency. This year gave me many disconnected ones: source files, study-material generation, exam questions, fact-checking, and correction. The missing layer was not another chatbot. It was a durable, inspectable execution layer that could let a tutor meet a student where they are without forgetting what happened before.
Study Agent Harness is an open-source, provider-neutral core for that layer. A model may propose what to do, but it does not own learner state, course authority, source truth, or execution. The harness keeps canonical state in an append-only event stream, snapshots trusted sources, projects inspectable evidence, runs versioned skills through playbooks, and replays the same state deterministically. Provider adapters remain technical boundaries, so the core can work with different models and hosts.
The Build Week demo starts where a student is: “I have ten minutes. Help me understand heart valves.” The real offline trace captures a sanitized source snapshot, completes a grounded action, suspends to ask which valve deserves focus, refreshes evidence after the learner chooses the aortic valve, and resumes the exact continuation. The visible trace is completed → suspended → completed; scripted and recorded-provider decision adapters reproduce it without a network request.
The interface shown in the video is a demonstrative visualization created for the submission, not the shipped product UI. The displayed behavior and trace are grounded in the real offline harness; the product layer is intentionally left open for future verticals.
Build Week decisions
We deliberately focused this build on the reusable core instead of building a single rigid study application. The important boundaries are state outside the model, skills and playbooks as the portable behavior layer, technical-only provider adapters, and deterministic offline verification. Codex and GPT-5.6 were used through an adapted Agent Flywheel: approved specs were decomposed into dependency-aware beads, implemented in bounded slices, and closed with focused tests, architecture/semantic review, and durable handoffs. This made the workflow itself inspectable without claiming that Codex owns architecture approval or canonical learner state.
Roadmap
The first priority after Build Week is to harden the core and publish stable contributor contracts for hosts, skills, playbooks, persistence, and replay. The next architectural slice is a self-improvement proposal loop: when an agent encounters a capability boundary—such as an unsupported material type—it can record a structured proposal rather than silently inventing behavior. Proposals will pass through explicit human review, validation, scoped implementation, tests, and replay checks before becoming part of the harness. This is a direction for the next milestone, not a shipped v0.2 capability.
Once the core is robust, the same OSS foundation can support vertical products for biomedical, medical, legal, or other learning domains. Those products can own their own UI and subject-specific skills while reusing the same durable execution and trust boundary. The goal is a free, community-maintained core that students, teachers, and builders can embed rather than each rebuilding their own tutor runtime.
Challenges
The central challenge was keeping an adaptive tutor flexible without letting a model become the owner of authority, truth, or durable state. The implementation separates model decisions from trusted execution, makes suspension and resumption explicit, and tests failure paths offline.
Accomplishments
- Event-sourced canonical study state and deterministic replay
- Source snapshots and inspectable evidence state
- Provider-neutral skills, playbooks, capabilities, and adapter boundaries
- A bounded tutor host with clarification, recovery, and fail-closed behavior
- A clean-wheel, one-command offline anatomy demo
What we learned
Agentic tutoring benefits from a flexible conversation, but reliability comes from moving authority and truth outside the model. Small executable specs, deterministic fixtures, and explicit stop criteria made that boundary testable.
Repository and supported platform
- Repository: https://github.com/EbrahimAbdelwahed/study-agent-harness
- License: Apache-2.0
- Platform: Python 3.12 or 3.13; CI on Ubuntu, Build Week verification on macOS arm64
Log in or sign up for Devpost to join the conversation.