Keep Straight

Keep Straight is a local-first QA session recorder for developers working with AI coding agents.

The MVP is intentionally narrow: the agent runs the project checks in the normal shell, writes a structured QA session JSON file, and Keep Straight validates, stores, and displays that session in a local read-only UI.

Install

Keep Straight is not published to npm yet. For the current alpha, install from a checked-out source tree:

pnpm install
pnpm build
cd packages/cli
npm pack --pack-destination /tmp
npm install -g /tmp/keepstraight-keep-straight-0.1.0-alpha.0.tgz

Install the agent skill from this repository's skills/keep-straight directory using your agent's local skill installer.

If you only need to test the packed CLI locally, run:

pnpm smoke:packed

After the package is published with a next dist-tag, the install path will be:

npm install -g @keepstraight/keep-straight@next
npx skills add VasiliySoldatkin/keep-straight

Verify the install:

keep-straight --version
keep-straight doctor --json

Current local release gates pack and smoke-test the same artifact before publish. After a stable release is promoted, npm install -g @keepstraight/keep-straight will install the default release.

MVP Workflow

In a repository, ask your agent for a concrete QA/debugging goal:

/keep-straight Verify that signup rejects duplicate email and does not create a second user.

The skill guides the agent to:

1. run keep-straight prep --description "<request>"
2. read the generated prep file
3. create observable criteria before running commands
4. run focused project checks directly in the shell
5. capture command output, evidence, findings, and risk notes
6. write AgentOutputV1 JSON
7. run keep-straight show <agent-output.json>

Keep Straight then validates the JSON, copies approved artifacts into a local session sandbox, stores normalized data under the user's home directory, starts a loopback server, and opens the session UI.

show and open keep the local UI server process running. Stop it with Ctrl-C when you are done reviewing the session. For scripted imports, use sessions --json or report after import if you need a command that exits immediately.

Commands

MVP commands:

keep-straight --help
keep-straight --version
keep-straight doctor [--json]
keep-straight help agent
keep-straight prep --description "<request>"
keep-straight show <agent-output.json>
keep-straight open [session-id|latest] [--print-url] [--json] [--no-open]
keep-straight sessions [--json]
keep-straight report [session-id|latest] --format markdown

Planned after MVP:

keep-straight run
keep-straight verify
keep-straight start/status/stop
keep-straight mcp

What The UI Shows

The local UI focuses on the completed QA session:

• original request
• derived verdict and confidence
• test type map
• criteria and linked evidence
• command runs with status, exit code, and summaries
• findings and suspected root causes
• false-positive, false-negative, side-effect, environment, flaky, and coverage risks
• generated markdown report

The UI is read-only in the MVP. It does not stream live command output or edit sessions.

Local Data

Keep Straight stores indexed session data outside the repository by default:

~/.keep-straight/
  repos/
    <repo-hash>/
      db.sqlite
      artifacts/
        <session-id>/

This avoids noisy git status output and keeps bulky artifacts local. Project-local export can be added later as an explicit command.

Set KEEP_STRAIGHT_HOME to use a different state root:

KEEP_STRAIGHT_HOME=/tmp/keep-straight keep-straight doctor --json

Artifact Safety

Agent output may reference artifact files only from the repository root or the prep artifactInbox. During import, Keep Straight copies accepted artifacts into its own session storage and exposes only API artifact URLs to the UI. Public session responses do not include raw artifact input paths, original filesystem paths, or internal stored-relative paths.

Development Checks

pnpm check
pnpm smoke:packed

pnpm check runs linting, typechecking, tests, and production builds. pnpm smoke:packed builds the CLI package, packs it, installs the tarball into an isolated prefix, verifies the installed binary, and checks that README, LICENSE, web UI assets, and the Keep Straight skill are present in the packed install.

Design Principles

• Local-first: source code, logs, screenshots, traces, and reports stay on the user's machine.
• Agent-native: the skill defines the QA workflow and evidence contract.
• Evidence-driven: verdicts are derived from criteria and evidence, not raw agent confidence.
• Conservative by default: unsupported runner, live server, MCP, and hosted-dashboard behavior is roadmap, not MVP.

License

MIT