zettcode 0.1.0__tar.gz

zettcode-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+**/.venv/
+**/__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.coverage
+**/.pytest_cache/
+**/.ruff_cache/
+.zett-tool-output/
+.env
+.DS_Store

zettcode-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chang-LeHung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zettcode-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: zettcode
+Version: 0.1.0
+Summary: A focused terminal coding agent powered by zett-agent
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Project-URL: Issues, https://github.com/Chang-LeHung/zettcode/issues
+Author: Chang-LeHung
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,coding-agent,llm,terminal,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: pyperclip<2,>=1.9
+Requires-Dist: wcwidth<1,>=0.2
+Requires-Dist: zett-agent==0.1.0
+Description-Content-Type: text/markdown
+
+# ZettCode
+
+ZettCode is a focused terminal coding agent built on `zett-agent`. Its TUI owns
+raw terminal input, component layout, mouse interaction, and cell-level
+differential rendering directly; it does not use prompt-toolkit or another TUI
+framework.
+
+The agent runtime is published separately as
+[`zett-agent`](https://github.com/Chang-LeHung/zett-agent); this repository owns
+only the terminal client.
+
+## Install
+
+ZettCode needs Python 3.14 or newer and is published on PyPI as `zettcode`:
+
+```bash
+uv tool install zettcode
+# or
+pip install zettcode
+```
+
+## Run
+
+DeepSeek:
+
+```bash
+export DEEPSEEK_API_KEY=...
+zettcode --provider deepseek --model deepseek-chat
+```
+
+OpenAI or an OpenAI-compatible endpoint:
+
+```bash
+export OPENAI_API_KEY=...
+zettcode --provider openai --model gpt-5-mini
+zettcode --provider openai --model my-model --base-url https://example.com/v1
+```
+
+Pass a workspace path as the final argument. It defaults to the current directory.
+Session data is stored in `~/.zettcode/sessions.sqlite3` by default.
+
+From a source checkout, run the same commands through `uv`:
+
+```bash
+uv sync
+uv run zettcode --provider deepseek --model deepseek-chat
+```
+
+## Keys
+
+- `Enter`: send
+- `Esc`, then `Enter`: insert a newline
+- `Ctrl-C`: stop the active request, or clear the input
+- `Ctrl-D`: delete the next character; exit when the input is empty and the agent is idle
+- `Ctrl-A` / `Ctrl-E`, `Home` / `End`: move to the start or end of the current line
+- `Ctrl-B` / `Ctrl-F`, `Left` / `Right`: move by one character
+- `Alt-B` / `Alt-F`, `Ctrl-Left` / `Ctrl-Right`: move by one word
+- `Ctrl-Home` / `Ctrl-End`, `Alt-<` / `Alt->`: move to the start or end of the whole input
+- `Ctrl-U` / `Ctrl-K`: delete to the start or end of the current line
+- `Ctrl-W` / `Alt-Backspace`, `Alt-D`: delete the previous or next word
+- `Ctrl-Y`: paste the last text removed with a line or word deletion
+- `Ctrl-Z` / `Ctrl-_`: undo the latest input edit
+- `Up` / `Down`: move between input lines, then browse submitted input history
+- `Ctrl-P` / `Ctrl-N`: browse submitted input history directly
+- `Ctrl-R`: search backward through submitted input history
+- `Ctrl-L`: redraw the terminal
+- `Ctrl-T`: expand or collapse the latest thinking block
+- `Page Up` / `Page Down`: scroll history while keeping the composer focused
+- Click the transcript and use `Up` / `Down`, `Home` / `End` to browse it
+- Drag in the transcript to select text; dragging past an edge automatically scrolls
+- Double-click a transcript row to select the complete visible line
+- `Shift`-click extends the existing selection
+- Completed mouse selections are copied to the system clipboard automatically
+- `Ctrl-C` also copies a transcript selection and returns focus to the input
+- `Tab` / `Shift-Tab`: complete slash commands
+
+Thinking is collapsed by default. Click a Thinking row to inspect it; moving the
+pointer outside that block collapses it again. Tool calls keep their output and
+completion status visible in the transcript. Active thinking and tool rows use a
+low-frequency moving highlight wave with an animated activity icon. Tool results show a five-row preview by default;
+click a completed tool row to expand it. Expanded output is still bounded so a
+large command result cannot take over the terminal or exhaust renderer memory.
+
+Assistant text renders common terminal-friendly Markdown: bold and emphasis,
+headings, inline and fenced code, links, quotes, unordered bullet lists, and
+GFM-style tables. Tables preserve left, center, and right alignment, account for
+wide CJK characters, and fit or truncate columns to the current terminal width.
+
+Use `/help` inside the application to see session commands.

zettcode-0.1.0/README.md

@@ -0,0 +1,89 @@
+# ZettCode
+
+ZettCode is a focused terminal coding agent built on `zett-agent`. Its TUI owns
+raw terminal input, component layout, mouse interaction, and cell-level
+differential rendering directly; it does not use prompt-toolkit or another TUI
+framework.
+
+The agent runtime is published separately as
+[`zett-agent`](https://github.com/Chang-LeHung/zett-agent); this repository owns
+only the terminal client.
+
+## Install
+
+ZettCode needs Python 3.14 or newer and is published on PyPI as `zettcode`:
+
+```bash
+uv tool install zettcode
+# or
+pip install zettcode
+```
+
+## Run
+
+DeepSeek:
+
+```bash
+export DEEPSEEK_API_KEY=...
+zettcode --provider deepseek --model deepseek-chat
+```
+
+OpenAI or an OpenAI-compatible endpoint:
+
+```bash
+export OPENAI_API_KEY=...
+zettcode --provider openai --model gpt-5-mini
+zettcode --provider openai --model my-model --base-url https://example.com/v1
+```
+
+Pass a workspace path as the final argument. It defaults to the current directory.
+Session data is stored in `~/.zettcode/sessions.sqlite3` by default.
+
+From a source checkout, run the same commands through `uv`:
+
+```bash
+uv sync
+uv run zettcode --provider deepseek --model deepseek-chat
+```
+
+## Keys
+
+- `Enter`: send
+- `Esc`, then `Enter`: insert a newline
+- `Ctrl-C`: stop the active request, or clear the input
+- `Ctrl-D`: delete the next character; exit when the input is empty and the agent is idle
+- `Ctrl-A` / `Ctrl-E`, `Home` / `End`: move to the start or end of the current line
+- `Ctrl-B` / `Ctrl-F`, `Left` / `Right`: move by one character
+- `Alt-B` / `Alt-F`, `Ctrl-Left` / `Ctrl-Right`: move by one word
+- `Ctrl-Home` / `Ctrl-End`, `Alt-<` / `Alt->`: move to the start or end of the whole input
+- `Ctrl-U` / `Ctrl-K`: delete to the start or end of the current line
+- `Ctrl-W` / `Alt-Backspace`, `Alt-D`: delete the previous or next word
+- `Ctrl-Y`: paste the last text removed with a line or word deletion
+- `Ctrl-Z` / `Ctrl-_`: undo the latest input edit
+- `Up` / `Down`: move between input lines, then browse submitted input history
+- `Ctrl-P` / `Ctrl-N`: browse submitted input history directly
+- `Ctrl-R`: search backward through submitted input history
+- `Ctrl-L`: redraw the terminal
+- `Ctrl-T`: expand or collapse the latest thinking block
+- `Page Up` / `Page Down`: scroll history while keeping the composer focused
+- Click the transcript and use `Up` / `Down`, `Home` / `End` to browse it
+- Drag in the transcript to select text; dragging past an edge automatically scrolls
+- Double-click a transcript row to select the complete visible line
+- `Shift`-click extends the existing selection
+- Completed mouse selections are copied to the system clipboard automatically
+- `Ctrl-C` also copies a transcript selection and returns focus to the input
+- `Tab` / `Shift-Tab`: complete slash commands
+
+Thinking is collapsed by default. Click a Thinking row to inspect it; moving the
+pointer outside that block collapses it again. Tool calls keep their output and
+completion status visible in the transcript. Active thinking and tool rows use a
+low-frequency moving highlight wave with an animated activity icon. Tool results show a five-row preview by default;
+click a completed tool row to expand it. Expanded output is still bounded so a
+large command result cannot take over the terminal or exhaust renderer memory.
+
+Assistant text renders common terminal-friendly Markdown: bold and emphasis,
+headings, inline and fenced code, links, quotes, unordered bullet lists, and
+GFM-style tables. Tables preserve left, center, and right alignment, account for
+wide CJK characters, and fit or truncate columns to the current terminal width.
+
+Use `/help` inside the application to see session commands.

zettcode-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "zettcode"
+version = "0.1.0"
+description = "A focused terminal coding agent powered by zett-agent"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Chang-LeHung"}]
+keywords = ["agent", "llm", "tui", "terminal", "coding-agent"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pyperclip>=1.9,<2",
+  "wcwidth>=0.2,<1",
+  "zett-agent==0.1.0",
+]
+
+[project.scripts]
+zettcode = "zettcode.cli:main"
+
+[project.urls]
+Repository = "https://github.com/Chang-LeHung/zettcode"
+Issues = "https://github.com/Chang-LeHung/zettcode/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zettcode"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/README.md", "/LICENSE", "/pyproject.toml"]
+
+[dependency-groups]
+dev = [
+  "pytest>=8,<9",
+  "pytest-asyncio>=0.26,<2",
+  "ruff>=0.11,<1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120
+target-version = "py314"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["zettcode"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"

zettcode-0.1.0/src/zettcode/__init__.py

@@ -0,0 +1,6 @@
+"""Terminal coding agent built on zett-agent."""
+
+from .config import ProviderName, ZettCodeConfig
+from .runtime import ZettCodeRuntime
+
+__all__ = ["ProviderName", "ZettCodeConfig", "ZettCodeRuntime"]

zettcode-0.1.0/src/zettcode/cli.py

@@ -0,0 +1,78 @@
+"""Command-line entry point for the ZettCode TUI."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+from pathlib import Path
+
+from zett_agent import ReasoningEffort
+
+from .config import ProviderName, ZettCodeConfig, default_model, provider_api_key
+from .runtime import ZettCodeRuntime
+from .tui import ZettCodeTUI
+
+
+def parse_args(argv: list[str] | None = None) -> ZettCodeConfig:
+    """Parse CLI arguments into a validated immutable configuration."""
+    default_provider = os.getenv("ZETTCODE_PROVIDER") or ProviderName.DEEPSEEK.value
+    parser = argparse.ArgumentParser(description="Run the ZettCode terminal coding agent")
+    parser.add_argument("workspace", nargs="?", type=Path, default=Path.cwd())
+    parser.add_argument("--provider", choices=[item.value for item in ProviderName], default=default_provider)
+    parser.add_argument("--model")
+    parser.add_argument("--api-key", help="Prefer provider environment variables to avoid shell history exposure")
+    parser.add_argument("--base-url")
+    parser.add_argument("--responses-api", action="store_true")
+    parser.add_argument("--session")
+    parser.add_argument("--database", type=Path, default=Path.home() / ".zettcode" / "sessions.sqlite3")
+    parser.add_argument(
+        "--reasoning-effort",
+        choices=[item.value for item in ReasoningEffort],
+        default=ReasoningEffort.MEDIUM.value,
+    )
+    parser.add_argument("--serial-tools", action="store_true")
+    parser.add_argument("--max-iterations", type=int, default=36)
+    parser.add_argument("--compaction-max-tokens", type=int, default=128_000)
+    parser.add_argument("--compaction-keep-tokens", type=int, default=32_000)
+    args = parser.parse_args(argv)
+    try:
+        provider = ProviderName(args.provider)
+    except ValueError:
+        parser.error(f"Unsupported provider: {args.provider!r} (check ZETTCODE_PROVIDER)")
+    try:
+        return ZettCodeConfig(
+            workspace=args.workspace,
+            provider=provider,
+            model=args.model or default_model(provider),
+            api_key=args.api_key or provider_api_key(provider),
+            database=args.database,
+            session_id=args.session,
+            base_url=args.base_url,
+            responses_api=args.responses_api,
+            reasoning_effort=ReasoningEffort(args.reasoning_effort),
+            parallel_tool_call=not args.serial_tools,
+            max_iterations=args.max_iterations,
+            compaction_max_tokens=args.compaction_max_tokens,
+            compaction_keep_tokens=args.compaction_keep_tokens,
+        )
+    except ValueError as error:
+        parser.error(str(error))
+
+
+async def async_main(config: ZettCodeConfig) -> None:
+    """Own runtime lifecycle around the full-screen application."""
+    runtime = await ZettCodeRuntime.create(config)
+    try:
+        await ZettCodeTUI(runtime).run()
+    finally:
+        await runtime.aclose()
+
+
+def main() -> None:
+    """Installed console-script entry point."""
+    asyncio.run(async_main(parse_args()))
+
+
+if __name__ == "__main__":
+    main()

zettcode-0.1.0/src/zettcode/config.py

@@ -0,0 +1,72 @@
+"""Validated construction settings for the ZettCode runtime."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+from zett_agent import ReasoningEffort
+
+
+class ProviderName(StrEnum):
+    """Provider adapters exposed by the initial CLI."""
+
+    DEEPSEEK = "deepseek"
+    OPENAI = "openai"
+
+
+@dataclass(frozen=True, slots=True)
+class ZettCodeConfig:
+    """All process-level settings needed to construct one coding runtime."""
+
+    workspace: Path
+    provider: ProviderName
+    model: str
+    api_key: str
+    database: Path
+    session_id: str | None = None
+    base_url: str | None = None
+    responses_api: bool = False
+    reasoning_effort: ReasoningEffort = ReasoningEffort.MEDIUM
+    parallel_tool_call: bool = True
+    max_iterations: int = 36
+    compaction_max_tokens: int = 128_000
+    compaction_keep_tokens: int = 32_000
+
+    def __post_init__(self) -> None:
+        workspace = self.workspace.expanduser().resolve()
+        database = self.database.expanduser().resolve()
+        if not workspace.is_dir():
+            raise ValueError(f"Workspace is not a directory: {workspace}")
+        if not self.model.strip():
+            raise ValueError("Model cannot be empty")
+        if not self.api_key.strip():
+            raise ValueError(f"Missing API key for {self.provider.value}")
+        if self.max_iterations < 1:
+            raise ValueError("max_iterations must be positive")
+        if self.compaction_keep_tokens < 1:
+            raise ValueError("compaction_keep_tokens must be positive")
+        if self.compaction_max_tokens <= self.compaction_keep_tokens:
+            raise ValueError("compaction_max_tokens must be greater than compaction_keep_tokens")
+        object.__setattr__(self, "workspace", workspace)
+        object.__setattr__(self, "database", database)
+
+
+def provider_api_key(provider: ProviderName) -> str:
+    """Read the selected provider credential without logging it."""
+    match provider:
+        case ProviderName.DEEPSEEK:
+            return os.getenv("DEEPSEEK_API_KEY") or os.getenv("DEEPSEEK_API", "")
+        case ProviderName.OPENAI:
+            return os.getenv("OPENAI_API_KEY", "")
+
+
+def default_model(provider: ProviderName) -> str:
+    """Return a conservative default model for one provider."""
+    match provider:
+        case ProviderName.DEEPSEEK:
+            return "deepseek-chat"
+        case ProviderName.OPENAI:
+            return "gpt-5-mini"

zettcode-0.1.0/src/zettcode/runtime.py

@@ -0,0 +1,121 @@
+"""Application runtime that composes AgentClient with coding extensions."""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from dataclasses import dataclass
+from datetime import datetime
+
+from zett_agent import (
+    AgentClient,
+    AgentRunConfig,
+    CodingExtension,
+    CompactionExtension,
+    DeepSeekProvider,
+    OpenAIProvider,
+    SQLiteSessionExtension,
+    ToolGuidelinesExtension,
+    create_agent,
+    new_uuid7,
+)
+
+from .config import ProviderName, ZettCodeConfig
+
+
+def build_system_prompt(config: ZettCodeConfig) -> str:
+    """Build request instructions with an explicit workspace boundary."""
+    now = datetime.now().astimezone()
+    return f"""You are ZettCode, a focused coding agent working with the user in one local workspace.
+
+Inspect relevant files before editing. Make focused changes, preserve unrelated work,
+and run checks proportional to risk. Explain blockers concretely. Do not perform
+destructive actions unless the user explicitly requests them.
+
+Runtime environment:
+- Workspace: {config.workspace}
+- Local time: {now.isoformat(timespec="seconds")}
+- Operating system: {platform.platform()}
+- Architecture: {platform.machine() or "unknown"}
+- Python: {platform.python_implementation()} {platform.python_version()}
+- Executable: {sys.executable}
+- Shell: {os.getenv("SHELL", "unknown")}
+
+Treat the workspace as the current working directory. Prefer relative paths in tool
+calls. Verify mutable facts with tools instead of assuming this startup snapshot is current."""
+
+
+@dataclass(slots=True)
+class ZettCodeRuntime:
+    """Own the model, persistence extension, AgentClient, and active session."""
+
+    config: ZettCodeConfig
+    client: AgentClient
+    persistence: SQLiteSessionExtension
+    model: OpenAIProvider | DeepSeekProvider
+    session_id: str
+
+    @classmethod
+    async def create(cls, config: ZettCodeConfig) -> ZettCodeRuntime:
+        """Create all owned resources after changing into the chosen workspace."""
+        os.chdir(config.workspace)
+        config.database.parent.mkdir(parents=True, exist_ok=True)
+        persistence = SQLiteSessionExtension(config.database)
+        recent = await persistence.list_sessions(limit=1)
+        session_id = config.session_id or (recent[0].session_id if recent else new_uuid7())
+        match config.provider:
+            case ProviderName.DEEPSEEK:
+                model = DeepSeekProvider(
+                    config.model,
+                    config.api_key,
+                    base_url=config.base_url,
+                    response=config.responses_api,
+                )
+            case ProviderName.OPENAI:
+                model = OpenAIProvider(
+                    config.model,
+                    config.api_key,
+                    base_url=config.base_url,
+                    response=config.responses_api,
+                )
+        try:
+            client = await create_agent(
+                model,
+                config=AgentRunConfig(session_id=session_id),
+                system_prompt=build_system_prompt(config),
+                extensions=[
+                    CodingExtension(),
+                    persistence,
+                    ToolGuidelinesExtension(),
+                    CompactionExtension(
+                        model,
+                        max_tokens=config.compaction_max_tokens,
+                        keep_recent_tokens=config.compaction_keep_tokens,
+                    ),
+                ],
+                reasoning_effort=config.reasoning_effort,
+                parallel_tool_call=config.parallel_tool_call,
+                max_iterations=config.max_iterations,
+            )
+        except BaseException:
+            await model.aclose()
+            await persistence.close()
+            raise
+        return cls(config, client, persistence, model, session_id)
+
+    def new_session(self) -> str:
+        """Switch future requests to a fresh session identity."""
+        self.session_id = new_uuid7()
+        return self.session_id
+
+    def use_session(self, session_id: str) -> None:
+        """Select a persisted or new explicit session for the next request."""
+        if not session_id.strip():
+            raise ValueError("Session ID cannot be empty")
+        self.session_id = session_id.strip()
+
+    async def aclose(self) -> None:
+        """Release all resources owned by this runtime."""
+        await self.model.aclose()
+        await self.persistence.close()