dshline: Instructions file for Codex

AGENTS.md

Instructions for an agent — or a person — working on this repository. If you want to use the interface, start at README.md. If you want to send a change, read CONTRIBUTING.md as well.

Read docs/design.md before changing anything about drawing, keyboard decoding, or text escaping. This file is the short version: the rules, the commands, and the mistakes that are easy to make.

What this project is

A terminal interface for DeepSeek Harness. It runs as a plugin inside the agent's own process, rather than as a client connecting over a network. There are two packages:

packages/renderer      @dshline/renderer   widths, keys, input line, boxes, screen — knows nothing about agents
packages/dshline       @dshline/dshline    the plugin: session loop, transcript, harness integration, view registry
packages/dshline/bin   dshline             a launcher wrapper, and deliberately nothing more

bin/dshline.mjs exists so that using this does not require remembering two things (dsh, --profile dshline). It finds the harness launcher, adds the profile and the working folder, and hands over the terminal with stdio: 'inherit'. It must never grow session logic: one implementation of the frontend is the point, and a wrapper that started doing its own work would be a second one.

Its one lifecycle involvement is the first run: with no dshline profile yet, it asks once and — if told yes — runs dsh plugin --profile dshline add @dshline/dshline through that same launcher, then continues into the launch that was asked for. It writes no profile file, never calls pnpm, and never repairs a profile that already exists — and it never decides that someone else's in-flight setup has finished, which is why the mutation runs whenever permission was given. See docs/architecture.md for where that boundary is drawn and why.