Contributing

English | 中文

Thank you for looking. Bug reports, terminal evidence, documentation fixes, and focused pull requests all help make dshline a dependable terminal presentation layer for the DeepSeek Harness plugin ecosystem.

Please read this page before opening a pull request. It is short.

What is most useful right now

• Generic Harness capability adapters. Prefer a standard capability surface to a provider-specific integration, and keep Harness as the authority for state, runtime, persistence, and policy.
• Terminal robustness. Reports and fixes for keyboard decoding, resize and geometry behavior, terminal restoration, or unreadable output are especially valuable. Include your terminal, operating system, width in columns, and a screenshot where useful.
• Cross-platform and Unicode evidence. Windows terminal testing, macOS terminals other than Ghostty, Linux PTY coverage, and CJK/wide-character correctness all protect the native terminal model.
• Sessions, attachments, and focused UX. Improvements should use Harness authority rather than add a parallel database, provider connection, or full-screen transcript.
• Documentation that did not match reality, or that you had to read twice to understand. Clear writing is a correctness concern, not a matter of taste.

The canonical Roadmap gives product direction and limitations; please do not duplicate it in an issue or pull request description.

Reporting a bug

Open an issue with:

• What you did, what you expected, and what happened instead.
• Your terminal program and version, your operating system, and the output of node --version.
• The output of dsh --profile dshline --dump-config, if the problem is about installing or about which plugins loaded.

For a key that does nothing, the most useful thing you can send is what your terminal actually sends. This prints it:

pnpm build && node tools/keyprobe.mjs

Press the key that misbehaves. Each line shows the raw bytes and the key this project decodes them into. An empty [] means the key was not recognised — copy those lines into the issue, along with your terminal's name.

Do not report security vulnerabilities in a public issue. See SECURITY.md for the private route.

Sending a change

1. Open an issue first for anything larger than a focused fix, so you do not spend time on something that does not fit the architecture or roadmap.
2. Read AGENTS.md. It lists the rules that are easy to break by accident and explains why the renderer, Harness wiring, and terminal model stay separate.
3. Add a test that fails without your change. Then break your own fix on purpose and confirm the test notices. A test that also passes against the broken version does not protect anything.
4. For a user-visible package change, run pnpm changeset and commit its Markdown file. Documentation, CI, and internal-only changes do not need one. AGENTS.md explains the version PR and tag flow.
5. Do not add dependencies. The renderer has none, and that is a deliberate feature. A change that needs a new package needs a discussion first.
6. Explain the reason in the commit message. Say what a user saw, why the obvious fix is wrong, and how you checked yours. Long commit messages are normal here.

pnpm install
pnpm build        # also required before testing by hand; see AGENTS.md
pnpm test         # the full suite, no terminal and no model needed
pnpm typecheck
pnpm security     # the dependency and workflow checks that CI runs

All of these must pass. CI runs them on Node 22.19, 24, and 26, plus the Minimum and Released Harness compatibility lanes, and every check is required before a merge.

Opt-in real Codex acceptance

The generic Work adapter also has a real-provider acceptance check. It is not part of normal CI: it starts the package-managed Codex app server and requires your local Codex authentication. Run it from the repository root with:

pnpm test:codex

It uses a temporary empty workspace, verifies generic subagent/start and subagent/end through Work and its existing overlay, then waits for the managed process tree to exit. Do not set the variable in CI.

What may be declined

Being honest about this saves your time:

• A new dependency, unless it replaces something clearly worse.
• A provider-specific implementation where a standard Harness capability surface can supply the same fact.
• A rewrite onto a UI framework. The append-plus-live-region terminal model is intentional; see Design.
• Features that need a full-screen layout, such as split panes or side panels. This interface prints into native terminal scrollback, which deliberately rules those out.

What to expect

This is not a funded project, and reviews may take a few days. A pull request sitting without a reply has not been rejected — please comment on it again.

By contributing, you agree that your contribution is licensed under the MIT License, like the rest of the project.