seektty

Project overview

Run deepseek from a project directory to use the native Agent, Session, model, permission, Settings, Profile, plugin, and persistence services of DeepSeek Harness from one terminal workspace. Prompts, code changes, tool calls, sessions, model routes, permissions, plugins, subagents, and diagnostics all operate on the same Harness state.

When an idea still needs definition, the optional plugin-backed /clarify workflow reads the active Session and composer draft, follows the real model route, and generates Socratic questions, contextual options, and a live draft preview that evolves after every answer. Accepting the preview places a complete Draft back in the ordinary composer for review and manual submission. Harness native /plan can then turn the clarified requirement into an implementation plan.

The Clarify Host plugin owns the Session-bound clarification process, model-generated questions, options, previews, and six-method Remote. When that compatible plugin capability is active, SeekTTY detects it and adds the local /clarify command plus its keyboard-first TUI surface. SeekTTY passes the current Session and draft to the plugin, then writes an accepted Draft back into the composer.

Clarify model calls run through Auxiliary Runtime and are recorded in its dedicated auxiliary_runtime ledger. Official Agent-loop usage remains in tokenUsage; SeekTTY /status shows separately sourced Official, Auxiliary, and derived Combined totals while the snapshot contract is healthy.

DeepSeek light and dark interfaces

Light theme

Dark theme

The live view fills the terminal and keeps the composer and status at the bottom. Unused rows remain inside the conversation viewport and disappear as output grows; longer conversations continue into native terminal scrollback.

Clarify and Plan

Clarify is an optional DeepSeek Harness Host plugin, and SeekTTY is its keyboard-first terminal consumer. Plugin-backed Clarify and Harness-native Plan cover consecutive parts of one workflow.

Clarify handles the stage where the desired outcome still needs definition. It uses the current Session and draft to ask one focused question at a time, carries accepted decisions forward, and updates a reviewable Draft after every answer. Accepting returns that Draft to the composer. You can edit it and press Enter when it represents what you want.

Plan handles the stage where the requirement is ready for implementation. Harness native /plan turns the submitted requirement into an implementation proposal and opens the normal plan-review flow.

Where /clarify comes from

The standalone SeekTTY shell presents its core command catalog. Activating the two Host plugins in the same Profile expands that catalog with the complete /clarify workflow.

[Active Session + composer draft]
              |
              v
     +------------------+      clarify Remote      +------------------+
     | SeekTTY consumer | -----------------------> | Clarify plugin   |
     | /clarify adapter | <----------------------- | process / model  |
     +--------+---------+   live Draft preview     +--------+---------+
              |                                            |
              |                                            | same-process run
              |                                            v
              |                                   +-------------------+
              |                                   | Auxiliary Runtime |
              |                                   | limits / cancel   |
              |                                   | usage ledger      |
              |                                   +---------+---------+
              |                                             |
              |                                             v
              |                                   [official model route]
              |                                   off-transcript, no-tools
              |
              | accept: Draft returns to the composer
              v
        [review and edit]
              |
              | press Enter
              v
     [formal Session message]
              |
              | /plan when an implementation plan is useful
              v
     [plan review -> Agent execution]

Auxiliary snapshot ---------------------> SeekTTY /status
                                          Official | Auxiliary | Combined

Main Session transcript

Questions, options, preview revisions, and refine feedback live in a temporary clarification process held in Host memory. It enters stale after 15 minutes without interaction by default and reports staleReason=ttl-expired. The main Session transcript receives the formal user message only after you submit the accepted Draft. Clarification state stays out of the input queue, pending interactions, Plan, Goal, Profile files, and SeekTTY local files.

Auxiliary model usage

Each Clarify model call is recorded by Auxiliary Runtime in the official storageDomain under auxiliary_runtime. Official tokenUsage continues to represent Agent-loop calls. Auxiliary derives Combined values from the four disjoint buckets—uncachedInputTokens, outputTokens, cacheReadTokens, and cacheWriteTokens—at read time, and SeekTTY /status validates and displays the snapshot. The auxiliary ledger stores call identity, purpose, status, token buckets, normalized failures, and timestamps; prompts, message text, model output, custom answers, credentials, and filesystem paths stay outside the ledger.

Start plugin-backed Clarify from the composer

SeekTTY adds /clarify to its local command catalog while the dsh-plugin-clarify Host plugin exposes a compatible six-method Remote with clarify.wire/1. The last jointly accepted Release still installs Clarify 0.2.1; 0.2.0 remains an available rollback artifact. The unpublished trio SeekTTY 1.2.1 + Auxiliary Runtime 0.1.1 + Clarify 0.2.2 has Lane A no-key PTY evidence and 2026-08-22 Lane B live-provider observations on candidate4. This is not a Release or complete joint acceptance. Details are in Verified scope.

• Run it from the command palette to keep the whole composer as the seed.
• Type /clarify some text to use the argument as the seed.
• End an existing draft with a standalone /clarify token or line to use the preceding draft as the seed.

Every answer refreshes the live Draft preview. The number of questions follows the unresolved decisions in the current Session: Clarify usually asks one focused question at a time and moves directly to review when the preview is ready to send. You can answer, refine the preview directly, accept it, or cancel. Accepting writes the reviewed Draft into the ordinary composer; Enter remains the explicit send action.

Custom interface and code themes, including VS Code imports

Theme customization is a first-class SeekTTY feature: interface background and text colors are editable, code-block colors and syntax styles are independently editable, and /theme import accepts local VS Code JSON/JSONC themes with portable TextMate token colors. A palette of 3–16 colors can also generate a complete light or dark theme for preview and further adjustment.

TypeScript in the DeepSeek light interface

Tool parameters, file reads, and Diff in the DeepSeek dark interface

Markdown fences disappear into continuous code surfaces. Assistant code, Shell commands, structured tool parameters, file reads, JSON, and Diff use the same active code theme; ordinary conversation text keeps the interface style. Every code background occupies continuous terminal cells and forms one uninterrupted surface.

Harness capabilities available in the TUI

The current release covers these capabilities:

Models, Providers, Agent Presets, permissions, Host commands, tools, Settings, Skills, MCP, and marketplace sources are discovered from the running Harness. New capabilities registered by upstream or third-party Bundles enter the dynamic catalogs, with Schema controls, structured details, and actionable diagnostics available while dedicated views evolve.

Quick start

The repositories and GitHub Releases are public. The last jointly accepted Clarify workflow remains official DeepSeek Harness 0.1.0-rc.8 with SeekTTY 1.2.0, Auxiliary Runtime 0.1.0, and Clarify 0.2.1. Install those published tarballs through the native dsh plugin command:

pnpm add --global @deepseek-ai/dsh@0.1.0-rc.8

dsh plugin --profile tui add https://github.com/Hilbert-beinghappy/seektty/releases/download/v1.2.0/seektty-1.2.0.tgz
dsh plugin --profile tui add https://github.com/Hilbert-beinghappy/dsh-plugin-auxiliary-runtime/releases/download/v0.1.0/dsh-plugin-auxiliary-runtime-0.1.0.tgz
dsh plugin --profile tui add https://github.com/Hilbert-beinghappy/dsh-plugin-clarify/releases/download/v0.2.1/dsh-plugin-clarify-0.2.1.tgz

dsh --profile tui

This path consumes packed artifacts and avoids Git-source prepare / allowBuilds. The first package installs the standalone SeekTTY shell, the second provides Auxiliary model execution, and the third provides the Clarify Host service and Remote. Once both Host plugins are active in the same Profile, SeekTTY discovers the Remote and adds /clarify to the terminal command catalog.

SeekTTY 1.2.1 currently tests official 0.1.1-rc.2. The unpublished trio SeekTTY 1.2.1 + Auxiliary Runtime 0.1.1 + Clarify 0.2.2 has Lane A no-key PTY evidence and 2026-08-22 Lane B live-provider observations on candidate4. This is not a Release or complete joint acceptance. Details are in Verified scope. There is no v1.2.1 Release asset yet; install this candidate from a locally packed tarball, or from a future GitHub Release listed at https://github.com/Hilbert-beinghappy/seektty/releases. Do not invent a download URL.

Bare deepseek launcher

SeekTTY supports macOS, Linux, and Windows. Install the same Release tarball globally; on Windows, pnpm add --global creates PATHEXT-aware shims for dsh.cmd.

pnpm add --global https://github.com/Hilbert-beinghappy/seektty/releases/download/v1.2.0/seektty-1.2.0.tgz
export SEEKTTY_SPEC=https://github.com/Hilbert-beinghappy/seektty/releases/download/v1.2.0/seektty-1.2.0.tgz
deepseek

PowerShell uses the same URL:

pnpm add --global 'https://github.com/Hilbert-beinghappy/seektty/releases/download/v1.2.0/seektty-1.2.0.tgz'
$env:SEEKTTY_SPEC='https://github.com/Hilbert-beinghappy/seektty/releases/download/v1.2.0/seektty-1.2.0.tgz'
deepseek

deepseek requires dsh on PATH, or DSH_BIN pointing at the executable. SEEKTTY_SPEC pins Profile reconciliation to the same prebuilt tarball. Without that override, this source tree's default spec is github:Hilbert-beinghappy/seektty#v1.2.1; that Git tag exists only after the Release is created. Until then, pack seektty-1.2.1.tgz and set SEEKTTY_SPEC to that file. Later runs boot the same Profile. Initial tasks, workspaces, Session resume, and custom Profiles are supported:

deepseek "check this project"
deepseek --cwd ../project
deepseek --resume
deepseek --resume <sessionId>
deepseek --profile team-tui
deepseek --version
deepseek --update

deepseek --update force-scans and installs at most one permitted component. Default SEEKTTY_UPDATE=auto: on launch it fetches official dsh npm latest (discovery only; not next or GitHub pre-releases) and the newest SeekTTY GitHub Release. SeekTTY is self-first: a SeekTTY update wins the round and skips dsh. Otherwise dsh installs only when latest is in the peer-aligned auto range (legacy rc.6–rc.8 or the exact current tested Host) and is newer than the installed dsh --version. Future or gap Hosts such as 0.1.1-rc.1 are mentioned but never installed. DSH_BIN pins skip dsh. Local link:/file: installs and SEEKTTY_SPEC overrides are left alone. Network or install failures never block boot. Set SEEKTTY_UPDATE=check to restore a post-session notice, or SEEKTTY_UPDATE=0 to disable.

First-run API key setup

When the active Profile has no usable model Provider, and the official DeepSeek Provider exposes a missing writable credential reference, SeekTTY opens a centered write-only prompt before the first interface frame. An existing environment credential, a credential already stored by Harness, or another active Provider that uses ambient or keyless authentication skips the prompt.

Dark first-run prompt

Light first-run prompt

Paste only the API key. Input is masked, and Enter passes the normalized value directly to Harness credentials.set; SeekTTY does not read it back, write a credential file, or place it in settings, logs, screenshots, or Session data. Saving does not send a paid validation request—the first real model request reports any authentication failure through the normal Harness Provider error path.

Escape defers setup without blocking /settings, /plugin, or other local surfaces. Sending a normal prompt, a Skill command, or a prompt with attachments opens the same setup again. An initial deepseek "task", submitted text, and draft attachments remain intact; after a successful save the pending prompt continues automatically, while another deferral restores it to the composer. If Provider inspection is unavailable, the official adapter is absent, or the credential layer is read-only, SeekTTY avoids an unusable form and points to /settings and /doctor while preserving Harness behavior.

Slash commands

Typing / opens a searchable command and Skill menu. It merges SeekTTY commands, Host commands registered for the active Agent, and user-invocable Skills.

/plugin, /workspace, and /profile provide both complete interactive centers and direct subcommands. Unknown commands produce nearby suggestions and stay within the command surface. SeekTTY detects the Clarify plugin's compatible six-method Remote with clarify.wire/1 and dynamically adds /clarify to the local / catalog. The plugin's model-generated questions, contextual options, and evolving preview lead to a reviewed Draft in the ordinary composer; you decide when to submit it. See Clarify and Plan for the full journey.

Common controls

Migrate from deepseek-tui

Replace the former global package once. The new deepseek launcher then uses native dsh plugin commands to replace the legacy Bundle identity in the target Profile with seektty:

pnpm remove --global deepseek-tui
pnpm add --global https://github.com/Hilbert-beinghappy/seektty/releases/download/v1.2.0/seektty-1.2.0.tgz
export SEEKTTY_SPEC=https://github.com/Hilbert-beinghappy/seektty/releases/download/v1.2.0/seektty-1.2.0.tgz
deepseek

Custom Profiles migrate independently on first launch, for example deepseek --profile team-tui. Native dsh-only installations can migrate explicitly:

dsh plugin --profile tui remove deepseek-tui
dsh plugin --profile tui add https://github.com/Hilbert-beinghappy/seektty/releases/download/v1.2.0/seektty-1.2.0.tgz

Plug and unplug

Removal changes only the target Profile, never the dsh installation:

dsh plugin --profile tui remove seektty

Reinstall with the same native command:

dsh plugin --profile tui add https://github.com/Hilbert-beinghappy/seektty/releases/download/v1.2.0/seektty-1.2.0.tgz

Installation writes directly to the target Harness Profile dependencies, Bundle order, and pnpm lockfile. TUI /plugin and native dsh plugin operate on that same Profile state.

Plugin center

Bare /plugin opens the current Profile's plugin center, and /plugins is an alias. Direct subcommands include list, search, info, install, remove, update, reorder, source, and doctor.

• Search npm Registry by default, add JSON/HTTP Catalogs, and consume sources registered by other Harness Bundles.
• Install npm names, Git URLs, tarballs, file URLs, and local directories.
• Preflight dsh.bundle.patch, packed files, the final install spec, build scripts, and the target Profile.
• Restart immediately after install, removal, update, or reorder while restoring the workspace, session, draft, and attachments.
• Inspect version, source, publisher, Bundle state, load order, and actionable diagnostics.

Models, settings, and themes

/model discovers Providers, models, and reasoning efforts from Harness and immediately refreshes the effective model shown in the composer. /mode manages Agent Presets, while /permission manages the active session permission; each has a separate runtime meaning.

/settings lists every Settings namespace registered in the current Profile. Default model, default permission, default Agent mode, and marketplace sources have dedicated selectors. Boolean, enum, number, text, JSON, Secret, Credential Ref, and other fields remain editable through the generic Schema UI. It shows inherited values, user overrides, reset actions, and live/restart timing; revision checks protect concurrent writes. Secrets expose only whether a value is configured and use masked input.

SeekTTY terminal copy ships in Chinese and English. /language opens the language selector, and direct forms are available for scripts or quick switching:

/language auto
/language zh
/language en

The selection is stored by the official @deepseek-ai/dsh-client-locale Host plugin as locale.preference, so the TUI and Harness Web use the same explicit preference. auto removes that override: SeekTTY then checks LC_ALL, LC_MESSAGES, LANGUAGE, and LANG, while the browser keeps using its own platform-language fallback. Switching is live and rebuilds the terminal chrome and transcript presentation without changing model, tool, user, Provider, or plugin-authored content.

SeekTTY starts with its DeepSeek dark theme. /theme opens a complete theme center; built-in and named themes can also be managed directly:

/theme dark
/theme light
/theme code [auto|dark|light|<name>]
/theme use <name>
/theme edit [name]
/theme palette [name]
/theme import [name] [local-file]
/theme delete <name>

The interface theme and code-block theme are independent. /theme light, /theme dark, and /theme use <name> select a complete matching interface/code pair. With /theme code auto, code background, foreground, syntax colors, and dark/light direction follow the active interface theme, so DeepSeek light uses light code blocks. /theme code dark, /theme code light, or /theme code <name> explicitly overrides only code until another complete interface theme is selected. /theme edit changes a complete named theme, while /theme palette accepts 3–16 HEX/RGB color codes and builds dark and light candidates.

/theme import reads a local VS Code JSON/JSONC theme, recursively resolves relative include files, maps editor and semantic-token colors, and preserves portable TextMate foreground, background, bold, italic, underline, and strikethrough rules. An imported VS Code theme becomes the active code theme without replacing the current interface theme. Every customization path opens a live preview before saving. Low-contrast colors are never silently replaced; the preview identifies the affected roles and asks for a second confirmation.

Custom themes cover the terminal canvas, panels, selection, text, border, brand and status colors, code background and foreground, and semantic roles for comments, keywords, strings, numbers, constants, functions, types, variables, properties, parameters, operators, punctuation, tags, attributes, and regular expressions. Assistant Markdown code, Shell invocations, structured tool parameters, file reads, JSON, and Diff all use the same code theme. Tool calls render as a compact action/duration header followed by ⎿-connected invocation code; the duration advances from the Harness call timestamp while the tool is active and freezes at settlement. Collapsed cards retain the invocation while expanded cards add results. Common grammars are ready at startup; other supported grammars load on demand and redraw in place. Theme changes recolor existing messages without moving the transcript, losing expanded state, or changing the draft.

The interface selection, independent code selection, and named definitions live in the seektty-appearance Harness Settings namespace under revision protection. /settings can therefore edit the same data through its generic Schema UI. Theme names are case-insensitively unique; overwrites and deletion require confirmation. Deleting an active interface theme returns the interface to DeepSeek dark, while deleting an active code theme returns code to automatic pairing. VS Code font families and sizes are deliberately ignored because the terminal owns the character-grid font; imported bold/italic and related styles apply only to code tokens and never restyle ordinary Chinese, English, system text, or tool titles.

Verified scope

• Isolated install, configuration composition, and PTY boot against official stock @deepseek-ai/dsh@0.1.0-rc.8, plus the add/boot/remove/re-add contract against the declared minimum @deepseek-ai/dsh@0.1.0-rc.6.
• SeekTTY 1.2.1 currently tests official @deepseek-ai/dsh@0.1.1-rc.2 at the shell, unit, and typecheck layer. Lane A (2026-08-21, unmodified stock 0.1.1-rc.2, isolated DSH_HOME, real PTY, unpublished SeekTTY 1.2.1 + Auxiliary Runtime 0.1.1 + Clarify 0.2.2): /doctor 0 error / 0 warning, 99 plugins running; /status healthy; /clarify routed through Auxiliary, returned MISSING_CREDENTIAL without a key, and kept the composer; Vision-Exp was visible and selectable; a PNG attachment restored after /restart. Missing-source restore: unit tests keep the failure copy to a basename, cover both notice orders, and keep absolute paths out of the text; a real-PTY hardcopy/visible scan found only the ASCII basename vision-logo.png and none of private/tmp, /tmp, Users, or Volumes. That does not prove the restore error stayed visible after dismissing the no-key onboarding modal (Esc also clears notices). Lane B (2026-08-22, unmodified stock 0.1.1-rc.2, isolated DSH_HOME, candidate4): Vision-Exp was selected explicitly; a PNG image-only send succeeded, cleared attachments on send, and recognized the logo, but the image-only prompt with no question led the model to call read_image again; a real JFIF JPEG queued through SeekTTY was converted by the official Host to a PNG variant as usual, then OCR succeeded without tools; Clarify via Auxiliary completed 6 dynamic rounds, a 41-line full review, and a second-confirm accept back into the composer without auto-send; /status showed Official, Auxiliary, and Combined usage; an 895-file scan found 0 secret literals. This is not a Release or complete joint acceptance. It does not prove Web UI, GIF/WebP, over-limit rejection, JPEG original-byte passthrough, PNG without any tool use, this-round interruption recovery, or a cost/cache A/B.
• Last jointly accepted Release installation: Clarify 0.2.1 with SeekTTY 1.2.0, Auxiliary Runtime 0.1.0, and official dsh 0.1.0-rc.8. Clarify 0.2.1 preserves the six-method Remote, clarify.wire/1, and exact rc.8 compatibility boundary of 0.2.0.
• Clarify 0.2.0 live-provider acceptance covered model-generated questions/options/previews, multi-round preview evolution, review-and-accept into the composer without automatic submission, interruption recovery, usage provenance, and privacy.
• Clarify 0.2.1 post-release no-key acceptance re-downloaded and verified all three Release assets, passed stock add/boot/remove/re-add and /doctor with 0 errors, 0 warnings, and 99 plugins, then reached running, routed through Auxiliary, and returned the expected isolated-environment MISSING_CREDENTIAL result. Version 0.2.1 has not rerun live-provider multi-round acceptance or a cache/cost A/B.
• Historical standalone Clarify lifecycle evidence covers official dsh rc.6/rc.7/rc.8; the complete dynamic production boundary remains exact rc.8 with Auxiliary Runtime 0.1.0.
• Auxiliary calls persist usage/limits/cancel only in the auxiliary_runtime storage domain. Official Agent tokenUsage remains unchanged, while /status displays validated Official, Auxiliary, and derived Combined buckets only when the optional snapshot contract is healthy.
• Model listing, Provider/model/reasoning selection, request submission, and Harness error propagation.
• First-run Provider readiness, masked API-key setup, deferral and draft restoration, Harness credential persistence, and restart without another prompt under an isolated DSH_HOME.
• Real dark, light, and palette-generated PTY rendering, independent live interface/code switching, 80/120/160-column layouts, and persistence after restarting the same Profile.
• Chinese/English locale resolution, revision-protected shared preference writes, live terminal switching, and preservation of unknown external content.
• Native removal clears the dependency, Bundle, and config entries; re-add boots again.
• A fresh packed global install, with no workspace development dependencies or duplicate @deepseek-ai/* packages, exposes bare deepseek, provisions the tui Profile, and boots through the official dsh module fallback.
• A real native todo_write journey passes after installation; the package gate also rejects Profile-local copies of official identity-bearing Host packages and verifies that Cordis, API proxy, Session, and tool runtime resolve to the official fallback instance.
• Installation, startup, keyboard navigation, and terminal interaction are supported on macOS, Linux, and Windows.

A real first-run session was verified with a valid DeepSeek credential pasted into the masked overlay under an isolated DSH_HOME: v4-flash returned REALCHECK_58597, then used that answer in the next turn to return REALCHECK_58598. Restarting the same Profile did not reopen setup, the Harness credential file was mode 0600, and the credential never appeared in terminal output, screenshots, or the repository. The isolated credential store was removed after verification.

Reusable stock-dsh contract check:

DSH_BIN=/path/to/dsh \
SEEKTTY_SPEC=/path/to/seektty.tgz \
pnpm test:stock

Reusable cross-package doctor check:

CLARIFY_SPEC=/path/to/dsh-plugin-clarify.tgz \
pnpm test:clarify-doctor

Compatibility and upgrades

The current tested Host is official 0.1.1-rc.2. The shell's declared minimum remains official 0.1.0-rc.6, with shell lifecycle coverage on the legacy rc.6/rc.7/rc.8 line. The last jointly accepted Clarify + Auxiliary production combination is still exact 0.1.0-rc.8 with SeekTTY 1.2.0, Auxiliary Runtime 0.1.0, and Clarify 0.2.1. The unpublished trio SeekTTY 1.2.1 + Auxiliary Runtime 0.1.1 + Clarify 0.2.2 has Lane A no-key PTY evidence and 2026-08-22 Lane B live-provider observations on candidate4; this is not a Release or complete joint acceptance (see Verified scope). A newer dsh than tested still boots the shell with a notice; older than the shell minimum is rejected. The updater judges the actually installed dsh --version, prefers a SeekTTY self-first update, installs at most one component per round, and never installs a future or gap Host. The published Bundle does not install a second copy of Cordis or any @deepseek-ai/dsh-* Host package into a Profile: optional peers describe the host contract, while runtime imports resolve through the official $DSH_HOME/profiles/node_modules fallback. This preserves identity-bearing symbols such as the native tool scheduler. Pure client helpers that the official fallback does not ship are bundled instead. The Host plugin seektty/attachment-compat still runs immediately before api-gateway and adapts only the exact valid legacy image-limit capability shape; all other shapes fail closed. Future hosts are matched by capability and unsupported optional features degrade safely. A scheduled workflow scans the official npm latest dist-tag, upgrades development baselines only after pnpm run check, packed-launcher isolation, and the stock-dsh contract pass, then opens a pull request. npm next and GitHub harness pre-releases are not followed.

The source repository and its GitHub Releases are public. User packages come from the prebuilt tarball attached to the matching Release; there is currently no npm Registry release.