Maieutic

Maieutic provides the same two SocrAItes profiles in a VS Code extension and a standalone Rust terminal editor:

• SocrAItes Learn is a strictly read-only lead engineer. It teaches from verified code, moves visual focus one concept at a time, and leaves every change to the learner.
• SocrAItes Assist can perform explicitly approved mechanical editing, but it cannot execute commands or decide business behavior, contracts, security policy, or product semantics.

There is no third @socraites participant or Maieutic voice model. Learn and Assist are the only user-selectable SocrAItes profiles, and both use VS Code's native Voice Mode.

Native Voice Mode

Maieutic requires VS Code 1.132 or newer. Select SocrAItes Learn or SocrAItes Assist, choose any coding model from VS Code's normal Chat picker, then use the single Voice Mode control in the Chat input. Maieutic does not add another handset, microphone, text-to-speech control, chat participant, or model selector.

On first activation, Maieutic initializes only unset VS Code settings for Voice Mode, hands-free turn taking, spoken responses, visible live transcripts, and a 1.5-second trailing-silence threshold. Users can change every option in Voice Mode Settings, and Maieutic never replaces a value they have chosen.

Voice Mode keeps the selected profile and coding model authoritative:

1. VS Code records the learner's speech, submits its transcript into the currently selected Learn or Assist chat, and keeps the transcript visible.
2. The model selected in the normal Chat picker handles the request with that profile's tools and limits. This includes GitHub-hosted Copilot models and local or OpenAI-compatible endpoints added through Chat: Manage Language Models.
3. VS Code reads the visible response aloud, supports barge-in, and automatically returns to listening in hands-free mode.
4. SocrAItes completes its visual tool call before responding, so the verified focus or pointer remains visible while VS Code speaks. The tools never move the user's caret.

VS Code's built-in dictation uses an on-device multilingual Nemotron model. Full hands-free Voice Mode uses VS Code's hosted realtime voice service and requires its normal network and GitHub sign-in flow. Neither path requires an OpenAI subscription or a LocalAI speech server. Maieutic no longer ships platform-specific audio executables.

Coding Models

Configure coding models in VS Code with Chat: Manage Language Models. VS Code can connect to built-in providers, provider extensions, and compatible custom endpoints. A LocalAI coding model added there appears beside Copilot models and can be selected normally for either SocrAItes profile.

Maieutic never republishes, chooses, or saves a coding model. Coding requests follow the selected provider's subscription, consent, endpoint, and data-handling rules. Choose a model with tool-calling support for the SocrAItes visual and Assist tools.

Visual Tools

Compatible models can use three profile-allowed tools:

• #focusContent opens a workspace file and focuses a complete line range.
• #pointAtContent moves or clears a precise pointer inside that range without scrolling.
• #clearFocusContent removes the presentation.

Only workspace-relative paths are accepted. In a multi-root workspace, prefix ambiguous paths with the workspace folder name. The presentation uses VS Code theme colors and never selects, edits, or moves the user's caret.

Profile Boundaries

SocrAItes Learn

Learn can read and search the workspace, inspect problems and existing terminal output, ask questions, consult primary documentation, and delegate one bounded read-only discovery task. It cannot edit files, run commands or tests, stage or commit work, or generate paste-ready business implementation. Repository-specific walkthroughs show one verified concept and end with one learner gate.

Learner controls are semantic intents, not magic words. Natural requests such as “walk me through this,” “give me a clue,” “pause here,” or equivalent voice-transcription variants work like their shorter examples in the profile.

SocrAItes Assist

Assist can help with boilerplate, engineer-defined scaffolding, tests for already-established behavior, first-pass review, approved behavior-preserving refactors, verified documentation drafts, and debugging after the engineer supplies an attempt and evidence. It cannot write core business logic, invent contracts or domain types, run commands, add dependencies without separate approval, stage, commit, or publish work.

Terminal Editor

The maieutic binary is an opinionated terminal editor for the same Learn/Assist workflow. It keeps the code editor, streamed conversation, approval UI, model controls, and agent-controlled focus or pointer in one screen. The editor widget is pinned to EdTUI 0.11.6 behind Maieutic's small EditorPort adapter, so persistence and safety rules do not depend on EdTUI internals and the widget can be replaced without rewriting the application.

The TUI speaks Agent Client Protocol through exactly @agentclientprotocol/codex-acp@1.1.9 and @openai/codex@0.145.0. It always requests that exact pair with npx --yes --package=@agentclientprotocol/codex-acp@1.1.9 --package=@openai/codex@0.145.0 codex-acp, validates the adapter identity before creating a session, and clears any inherited CODEX_PATH; an arbitrary codex-acp or codex on the user's PATH is never trusted. The adapter protocol does not report the nested Codex executable's version, so the Codex pin is enforced by the exact npm request rather than a runtime identity assertion. This requires Node.js and network access the first time npm fills its cache. Authentication belongs to the adapter: Maieutic selects API-key authentication when CODEX_API_KEY or OPENAI_API_KEY is present, otherwise it selects ChatGPT browser authentication when browser login is allowed. Existing credentials may be read from an inherited CODEX_HOME, but persistent Maieutic credentials are written only under the user's default Codex home; each child still runs from a clean temporary Codex home. A browserless launch needs existing credentials or an API key. See the Codex ACP authentication documentation for the current choices.

The agent receives Maieutic's profile policy on every turn and an authenticated, random-port loopback MCP server exposing focus_content, point_at_content, and clear_focus. A visual tool is acknowledged only after the single-owner UI loop applies it. Visuals do not move the real editor caret, and focus or pointer changes are refused while the active document has unsaved edits.

Terminal safety boundaries

• Both profiles run with an exact enforced Codex configuration, forced human review, on-request approval, a read-only sandbox, and a protected ACP read-only mode. The same configuration is written with private permissions into the isolated CODEX_HOME before App Server starts and passed explicitly to every ACP thread. Apart from administrator-managed system policy, the only external MCP server configured by Maieutic is its authenticated loopback visual server. Codex's built-in read, search, and shell capabilities remain available under its read-only sandbox, while Maieutic cancels every non-file-change permission type. Inherited user and project config and adapter-specific executable, provider, logging, and MCP-filter overrides are replaced with known values; administrator-enforced Codex policy can still add restrictions or MCP servers. ACP itself runs in an empty temporary directory with project-root discovery and plugin, hook, skill, app, and workspace-dependency loading disabled; it receives no repository additional root, so repository .codex config, hooks, MCP servers, skills, and agent instructions cannot load implicitly during startup or session setup. Each prompt names the real workspace as an explicit absolute inspection target.
• --workspace is the intended agent inspection root and the enforced boundary for the editor, visual tools, and approved file changes. Agent read visibility follows Codex's read-only operating-system sandbox and may be broader than that root; do not use the preview as a confidential-file isolation boundary.
• The editor accepts existing UTF-8 files up to 8 MiB and 200,000 lines. Open, paste, and save paths reject terminal control bytes, mixed in-memory line endings, and content that would exceed those bounds.
• Learn cancels every permission request. Its profile policy additionally prohibits state-changing commands and implementation.
• Assist exposes only a one-time approval for an ACP file-change batch. The dialog shows each reported path and the first changed line, starts on Reject, and never offers session-wide approval. Before accepting, Maieutic verifies that every reported path remains inside the workspace, does not target a .codex control path, and still equals the displayed old text; after completion it verifies the reported approved result. Missing, oversized, stale, symlinked, outside-workspace, protected-control, or otherwise incomplete evidence is cancelled. Execute, fetch, mode-switch, and unknown permissions are never shown.
• The mutation boundary is technical; the narrower definition of appropriate mechanical work remains a profile policy. Both profiles keep staging, commits, pushes, publishing, secrets, and unresolved product or architecture decisions outside the intended workflow. Maieutic does not pretend a prompt can replace the adapter, operating-system sandbox, or engineer review.

Run the TUI

Running maieutic requires Node.js with npx; building it from source additionally requires Rust 1.88 or newer. CI and release builds use exactly Rust 1.88.0. Run the TUI once while online to populate npm's cache before relying on it offline.

Build and run from this checkout:

cargo build --locked --release --package maieutic-tui
cargo run --locked --release --package maieutic-tui -- README.md --workspace . --profile learn

Developer-preview archives contain the maieutic executable. Its first positional argument must be an existing UTF-8 file; --workspace sets the intended agent inspection root and the enforced editor, visual-tool, and approved-write boundary. --profile accepts learn or assist and defaults to learn. These preview binaries are not currently code-signed or notarized. They are intended for developers who can verify the published SHA256SUMS; operating-system reputation controls may block them or require an explicit local exception.

The editor uses EdTUI's Vim-style input: i enters Insert mode, Esc returns to Normal mode, and normal navigation includes the arrow keys or h, j, k, and l. Maieutic reserves these application controls:

The command composer accepts open PATH, write (or w), learn, assist, model, reasoning, cancel, quit (or q), quit! (or q!), and help. model and reasoning show only options advertised by the active ACP agent.

The terminal editor deliberately has no separate speech stack. VS Code's native Voice Mode remains the voice path for the extension.

Local Development

Install dependencies and a locally packaged development build:

npm install
npm run dev:install

Reload VS Code, run Maieutic: Show Build Info, and confirm the installed version. For TypeScript debugging, open this repository, press F5, and choose Run Maieutic against Cola.

Release checks:

• npm run check runs type checking, linting, and unit tests.
• npm test packages the extension and runs the Extension Host suite.
• npm run verify:release adds the production dependency audit.
• cargo fmt --all -- --check enforces Rust formatting.
• cargo check --locked --workspace --all-targets --all-features checks every TUI target.
• cargo clippy --locked --workspace --all-targets --all-features -- -D warnings applies the workspace's strict Clippy policy.
• cargo test --locked --workspace --all-targets --all-features runs the Rust unit and loopback integration tests.
• cargo audit checks Cargo.lock when cargo-audit is installed.
• test/manual/socraites-acceptance.md covers the profile, native Voice Mode, delegated model, transcript, audio, pointer, and barge-in contracts.

Publishing

Pushes and pull requests to main run .github/workflows/ci.yml for both the extension and terminal editor with Rust 1.88.0. A matching v* tag runs .github/workflows/release.yml: it verifies the TUI, tests and packages one VSIX, and builds every TUI archive before creating or updating the public GitHub Release. Only after that complete release succeeds does the workflow publish the same tested VSIX to the VS Code Marketplace with short-lived Microsoft Entra workload identity credentials. The unsigned developer-preview archives cover static-musl Linux x86-64, macOS x86-64 and Apple silicon, and Windows x86-64; they are GitHub Release assets and are never included in or substituted for the Marketplace VSIX.

For a release, update package.json, package-lock.json, cli/Cargo.toml, Cargo.lock, and CHANGELOG.md together, commit on main, then push the matching version tag. The workflow rejects a tag that does not match the shared extension/TUI version, either lockfile, or a commit on main.