Improve commands hints.

Author: beacoder

README.md

@@ -37,12 +37,12 @@ A Python port of the Emacs [gptel-agent-harness](https://github.com/beacoder/gpt
 - **Sessions** — auto-saved after every response to
   `~/.local/share/python-agent-harness/sessions/`, LLM-generated titles
   (one-shot per session, fired when the agent loop finishes; the file is
-  renamed to `<title>_<TS>.md`), `restore` (with `--latest`) /
-  `sessions` CLI commands.
-- **Commands** — `init` (create/update AGENTS.md), `review` (uncommitted
-  changes / commit / branch / PR), and custom commands from
-  `prompts/commands/*.txt`; `summary` and `explain` are TUI slash
-  commands only.  Tool availability: `init`/`review` may use **all
+  renamed to `<title>_<TS>.md`), `/restore` (with `--latest`) and
+  `/sessions` TUI commands.
+- **Commands** — `/init` (create/update AGENTS.md), `/review` (uncommitted
+  changes / commit / branch / PR), `/summary`, `/explain` and custom
+  commands from `prompts/commands/*.txt` — all TUI slash commands.
+  Tool availability: `/init`/`/review` may use **all
   tools except PlanExit** (the PlanExit tool is hidden for the run,
   including for spawned sub-agents); custom commands may use all tools
   including PlanExit; `compact`/`summary` run with **no tools** (a
@@ -129,8 +129,7 @@ TUI slash commands: `/plan` `/build` `/init` `/review` `/explain`
 `/restore` `/clear` `/exit` — `/explain [project] [target]` explains
 code and `/summary` appends a conversation summary (both TUI-only);
 `/sessions` lists saved sessions and `/restore [path|title|--latest]`
-restores one (they are also CLI subcommands; in the TUI, `/restore`
-additionally matches sessions by title substring).
+restores one (`/restore` matches sessions by title substring).
 
 Input editing: type your message, press **Enter** for a new line, and
 **Esc then Enter** (or **Alt+Enter**) to submit. **Up/Down** recall

python_agent_harness/cli.py

@@ -1,16 +1,12 @@
-"""CLI entry points: interactive TUI session and command-line commands.
+"""CLI entry points: interactive TUI session and configuration.
 
 Commands:
   run [project]            interactive TUI agent session (default)
   config [--init]          show effective LLM config / write a template file
-  init [project]           create/update AGENTS.md
-  review [args]            review uncommitted changes / commit / branch / PR
-  <custom>                 any prompt file in prompts/commands/ (except
-                           TUI-only slash commands such as explain)
-  summary                  summarize the current (saved) session
-  sessions                 list saved sessions
-  restore <file>           restore a saved session
-  restore-latest           restore the newest session
+  <custom>                 any prompt file in prompts/commands/
+
+init, review, sessions, restore (and summary/explain) are TUI slash
+commands only — see the TUI help for /init /review /sessions /restore.
 
 Configuration (LLM etc.) is read from a JSON file, by default
 ~/.config/python-agent-harness/config.json; see `config --init`.
@@ -28,7 +24,6 @@
     SessionCommand, find_command, load_custom_commands,
 )
 from .agent_session import AgentSession
-from .session_store import SessionStore
 from .tools import default_registry
 
 
@@ -127,16 +122,6 @@ def cmd_config(args: argparse.Namespace) -> int:
     return 0
 
 
-def cmd_init(args: argparse.Namespace) -> int:
-    _run_command(initialize_command(), args.project, args.extra, args.config)
-    return 0
-
-
-def cmd_review(args: argparse.Namespace) -> int:
-    _run_command(review_command(), args.project, args.arguments, args.config)
-    return 0
-
-
 def cmd_custom(args: argparse.Namespace) -> int:
     cmd = find_command(args.command_name)
     if cmd is None:
@@ -171,59 +156,6 @@ def _adopt(session: AgentSession, kw: dict) -> AgentSession:
     return session
 
 
-def cmd_sessions(args: argparse.Namespace) -> int:
-    files = SessionStore.list_sessions()
-    if not files:
-        print("no saved sessions")
-        return 0
-    for f in files:
-        try:
-            meta = SessionStore.parse_metadata(open(f, encoding="utf-8").read())
-        except OSError as e:
-            print(f"{os.path.basename(f):60s} (unreadable: {e})")
-            continue
-        print(
-            f"{os.path.basename(f):60s} "
-            f"model={meta.get('gptel-model', '?'):20s} "
-            f"project={meta.get('python-agent-harness--project-dir', '?')}"
-        )
-    return 0
-
-
-def cmd_restore(args: argparse.Namespace) -> int:
-    from .session_store import SessionStore as Store
-    from .session_store import title_from_filename
-
-    path = args.file
-    if not path and args.latest:
-        path = Store.latest_session()
-    if not path:
-        print("no session file given", file=sys.stderr)
-        return 1
-    try:
-        text = open(path, encoding="utf-8").read()
-    except OSError as e:
-        print(f"cannot read {path}: {e}", file=sys.stderr)
-        return 1
-    meta = Store.parse_metadata(text)
-    body = Store.strip_metadata(text)
-    project = meta.get("python-agent-harness--project-dir") or os.getcwd()
-    model = meta.get("gptel-model") or config.DEFAULT_MODEL
-    session = make_session(
-        project,
-        config_path=args.config,
-        model=model,
-    )
-    session.store.file_path = path
-    title = title_from_filename(path)
-    session.store.title = title
-    print(f"restored: {path} (project={project}, model={model})")
-    print("conversation preview:")
-    print("\n".join(body.splitlines()[:20]))
-    session.close()
-    return 0
-
-
 def _add_config_arg(
     parser: argparse.ArgumentParser, suppress: bool = False
 ) -> None:
@@ -255,16 +187,6 @@ def build_parser() -> argparse.ArgumentParser:
     p_config.add_argument("--path", metavar="PATH", help="config file path")
     p_config.set_defaults(func=cmd_config)
 
-    p_init = sub.add_parser("init", help="create/update AGENTS.md")
-    _add_config_arg(p_init, suppress=True)
-    p_init.add_argument("project", nargs="?", help="project directory")
-    p_init.add_argument("--extra", help="extra instructions")
-
-    p_review = sub.add_parser("review", help="review code changes")
-    _add_config_arg(p_review, suppress=True)
-    p_review.add_argument("project", nargs="?")
-    p_review.add_argument("arguments", nargs="?", help="commit/branch/PR, or empty")
-
     for cmd in load_custom_commands():
         if cmd.name in TUI_ONLY_COMMANDS:
             continue  # TUI slash command only (e.g. /explain)
@@ -273,15 +195,6 @@ def build_parser() -> argparse.ArgumentParser:
         p.add_argument("project", nargs="?")
         p.add_argument("extra", nargs="?", help="arguments for the command")
         p.set_defaults(func=cmd_custom, command_name=cmd.name)
-
-    p_sessions = sub.add_parser("sessions", help="list saved sessions")
-    p_sessions.set_defaults(func=cmd_sessions)
-
-    p_restore = sub.add_parser("restore", help="restore a saved session")
-    _add_config_arg(p_restore, suppress=True)
-    p_restore.add_argument("file", nargs="?", help="session file path")
-    p_restore.add_argument("--latest", action="store_true", help="restore newest session")
-    p_restore.set_defaults(func=cmd_restore)
     return parser
 
 
@@ -292,10 +205,6 @@ def main(argv: list[str] | None = None) -> int:
         return cmd_run(args)
     if args.command == "config":
         return cmd_config(args)
-    if args.command == "init":
-        return cmd_init(args)
-    if args.command == "review":
-        return cmd_review(args)
     if hasattr(args, "func"):
         return args.func(args)
     parser.print_help()

python_agent_harness/tui.py

@@ -574,7 +574,8 @@ def run(self) -> None:
                 "Type a message — Enter for a new line, Esc then Enter "
                 "(or Alt+Enter) to submit. Up/Down recall history.",
                 border_style="blue",
-            )
+            ),
+            markup=False,
         )
         if config.LLM_LOG_ENABLED:
             self.console.print(f"[dim]LLM logs: {self.session.client.log_path}[/dim]")
@@ -859,7 +860,8 @@ def _handle_slash(self, line: str) -> bool:
                 "/sessions                            list saved sessions\n"
                 "/restore [path | title | --latest]   restore a saved session\n"
                 "Ctrl-C cancels the current execution (app stays open); "
-                "Ctrl-D or /exit quits."
+                "Ctrl-D or /exit quits.",
+                markup=False,
             )
         else:
             self.console.print(f"unknown command: {cmd}")

tests/test_cli.py

@@ -106,7 +106,10 @@ def test_explain_not_a_cli_subcommand(self):
         )
         self.assertNotIn("explain", subparsers.choices)
         self.assertIn("run", subparsers.choices)
-        self.assertIn("review", subparsers.choices)
+        self.assertNotIn("review", subparsers.choices)
+        self.assertNotIn("init", subparsers.choices)
+        self.assertNotIn("sessions", subparsers.choices)
+        self.assertNotIn("restore", subparsers.choices)
         cmd = find_command("explain")
         self.assertIsNotNone(cmd)
         self.assertEqual(cmd.name, "explain")
@@ -209,36 +212,17 @@ def _loop(*a, **kw):
 
 
 class TestCliSessionCommands(unittest.TestCase):
-    def test_cmd_restore_unreadable_file(self):
-        """An unreadable session file must produce a clean error, not a
-        traceback."""
-        from types import SimpleNamespace
-
+    def test_removed_cli_subcommands(self):
+        """init/review/sessions/restore are TUI slash commands only."""
         from python_agent_harness import cli
 
-        args = SimpleNamespace(file="/tmp", latest=False, config=None)
-        self.assertEqual(cli.cmd_restore(args), 1)
-
-    def test_cmd_sessions_skips_unreadable_files(self):
-        """A session entry that cannot be read (e.g. a directory named
-        *.md) is listed as unreadable instead of crashing."""
-        import os
-        import tempfile
-        from pathlib import Path
-
-        from python_agent_harness import cli, config
-
-        with tempfile.TemporaryDirectory() as d:
-            old_dir = config.SESSION_DIR
-            config.SESSION_DIR = Path(d)
-            try:
-                sessions = Path(d) / "python-agent-harness" / "sessions"
-                sessions.mkdir(parents=True)
-                (sessions / "broken.md").mkdir()  # dir masquerading as a session
-                (sessions / "good_260805120000.md").write_text("hello")
-                self.assertEqual(cli.cmd_sessions(None), 0)
-            finally:
-                config.SESSION_DIR = old_dir
+        parser = cli.build_parser()
+        subparsers = next(
+            a for a in parser._actions
+            if a.__class__.__name__ == "_SubParsersAction"
+        )
+        for name in ("init", "review", "sessions", "restore"):
+            self.assertNotIn(name, subparsers.choices)
 
 
 def _load(path, project_dir=None, with_context=False):

tests/test_config.py

@@ -158,7 +158,7 @@ def test_config_flag_both_positions(self):
         self.assertEqual(before.config, "/x.json")
         after = parser.parse_args(["run", "/tmp", "--config", "/x.json"])
         self.assertEqual(after.config, "/x.json")
-        plain = parser.parse_args(["sessions"])
+        plain = parser.parse_args(["config"])
         self.assertIsNone(plain.config)
 
 

tests/test_tui.py

@@ -590,6 +590,14 @@ def test_help_lists_command_slashes(self):
         out = buf.getvalue()
         for s in ("/init", "/review", "/explain"):
             self.assertIn(s, out)
+        # bracket usage text must not be swallowed by rich markup
+        for s in (
+            "/init [project] [--extra TEXT]       create/update AGENTS.md",
+            "/review [project] [commit|branch|PR] review code changes",
+            "/explain [project] [target]",
+            "/restore [path | title | --latest]   restore a saved session",
+        ):
+            self.assertIn(s, out)
 
     def test_completer_slash_commands(self):
         from prompt_toolkit.document import Document