Metadata-Version: 2.2
Name: bisos.vscodeClaude
Version: 0.11
Summary: bisos.vscodeClaude: Command-Line Interfaces to VS Code and Its Claude Extension
Author: Mohsen Banan
Author-email: libre@mohsen.1.banan.byname.net
Maintainer: Mohsen Banan
Maintainer-email: libre@mohsen.1.banan.byname.net
License: AGPL
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: bisos
Requires-Dist: bisos.b
Requires-Dist: bisos.capability
Requires-Dist: bisos.common
Requires-Dist: bisos.csPlayer
Requires-Dist: bisos.sbom
Requires-Dist: setuptools==75.8.0
Requires-Dist: wheel==0.38.4
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: summary

===============================================================================
bisos.vscodeClaude: Command-Line Interfaces to VS Code and Its Claude Extension
===============================================================================

.. contents::
   :depth: 3
..

Overview
========

*bisos.vscodeClaude* drives the local (desktop) VS Code and its Claude
Code extension from the command line: open a file at a line, a folder, a
diff or a URI in VS Code; list the running Claude sessions; hand a
session a prompt, and optionally submit it. A shell, a script, Claude
itself, a VS Code task or an editor (Emacs) uses it the same way.

It is layer 2 of the AI-Activity layers (below): VS Code, with its
Claude extension. It also holds the Python of layers 3 and 4, as
separate modules, so that every command-line interface to VS Code is in
one package. It needs no editor: an AI-Activity conducted purely in VS
Code uses it from a shell. The Emacs side, layers 3 to 5, is the Blee
package `vscode-claude <https://github.com/bx-blee/vscode-claude>`__.

*For the local (desktop) VS Code; the remote VS Code server is not a
target.*

.. _table-of-contents:

Table of Contents TOC
=====================

-  `Overview <#overview>`__
-  `Its Place in the Layers <#its-place-in-the-layers>`__
-  `Part of BISOS — ByStar Internet Services Operating
   System <#part-of-bisos--bystar-internet-services-operating-system>`__
-  `bisos.vscodeClaude is a Command-Only PyCS
   Facility <#bisosvscodeclaude-is-a-command-only-pycs-facility>`__
-  `Installation <#installation>`__

   -  `Installation With pip <#installation-with-pip>`__
   -  `Installation With pipx <#installation-with-pipx>`__
   -  `Installing VS Code and Its Extensions:
      ``vscode-sbom.pcs`` <#installing-vs-code-and-its-extensions-vscode-sbompcs>`__
   -  `All at Once: the vscodeClaude Capability (CBS and
      CBM) <#all-at-once-the-vscodeclaude-capability-cbs-and-cbm>`__

-  `Usage <#usage>`__

   -  `VS Code Itself: ``vscode.cs`` <#vs-code-itself-vscodecs>`__
   -  `VS Code and Its Partner Emacs:
      ``vscode.cs`` <#vs-code-and-its-partner-emacs-vscodecs>`__
   -  `Its Claude Sessions:
      ``vscodeClaude.cs`` <#its-claude-sessions-vscodeclaudecs>`__
   -  `The Emacs Layer:
      vscode-claude <#the-emacs-layer-vscode-claude>`__

-  `Key Files <#key-files>`__
-  `Documentation and Blee-Panels <#documentation-and-blee-panels>`__
-  `Testing <#testing>`__
-  `Support <#support>`__
-  `Planned Improvements <#planned-improvements>`__

Its Place in the Layers
=======================

AI-Activity, VS Code and Emacs are layered; each layer is usable without
those above it, and a lower layer never names an upper one. The figure
of the layers and their three uses (VS Code only; Blee and VS Code
Claude; Blee, VS Code Claude and AI-Activity) is in the README of
`vscode-claude <https://github.com/bx-blee/vscode-claude>`__.

+---+--------------------+--------------------+--------------------+
| # | Layer              | Package            | Modules            |
+===+====================+====================+====================+
| 0 | Templates          | ``aiTem            | assembled into a   |
|   |                    | plates-workFlow``, | base               |
|   |                    | ``aiTemplates-DE`` |                    |
+---+--------------------+--------------------+--------------------+
| 1 | AI-Activity        | ``                 | ``aiActivity.cs``  |
|   |                    | bisos.aiActivity`` |                    |
+---+--------------------+--------------------+--------------------+
| 2 | VS Code (+ Claude) | **bi               | ``vscode_csu``     |
|   |                    | sos.vscodeClaude** |                    |
+---+--------------------+--------------------+--------------------+
| 3 | Emacs <-> VS Code  | **bis              | `                  |
|   |                    | os.vscodeClaude**, | `vscodeEmacs_csu`` |
|   |                    | Blee               |                    |
|   |                    | ``vscode-claude``  |                    |
+---+--------------------+--------------------+--------------------+
| 4 | Emacs <-> VS Code  | **bis              | ``                 |
|   | Claude             | os.vscodeClaude**, | vscodeClaude_csu`` |
|   |                    | Blee               |                    |
|   |                    | ``vscode-claude``  |                    |
+---+--------------------+--------------------+--------------------+
| 5 | + AI-Activity      | Blee               | (elisp only)       |
|   |                    | ``vscode-claude``  |                    |
+---+--------------------+--------------------+--------------------+

Layers 3 and 4 are each a Python half here and an elisp half in Blee.
Within this package the same rule holds: ``vscode_csu`` names neither
Emacs nor Claude, ``vscodeEmacs_csu`` names no Claude, and
``vscodeClaude_csu`` imports the two below it.

Part of BISOS — ByStar Internet Services Operating System
=========================================================

Layered on top of Debian, **BISOS** (By\* Internet Services Operating
System) is a unified and universal framework for developing both
internet services and software-service continuums that use internet
services. See `Bootstrapping ByStar, BISOS and
Blee <https://github.com/bxGenesis/start>`__ for information about
getting started with BISOS.

**BISOS** is a foundation for **The Libre-Halaal ByStar Digital
Ecosystem** which is described as a cure for losses of autonomy and
privacy in a book titled: `Nature of
Polyexistentials <https://github.com/bxplpc/120033>`__

*bisos.vscodeClaude* is part of BISOS. It is a standalone package that
can be used independently of the full BISOS environment.

bisos.vscodeClaude is a Command-Only PyCS Facility
==================================================

bisos.vscodeClaude is a command-line tool. It is a PyCS single-unit
command service. PyCS is a framework that converges development of CLI
tools and services. PyCS is an alternative to FastAPI, Typer and Click.

bisos.vscodeClaude uses the PyCS-Framework to:

#. inspect the local VS Code and open things in it (``vscode.cs``);
#. join VS Code with a partner Emacs, in both directions
   (``vscode.cs``);
#. list the VS Code Claude sessions and prompt them
   (``vscodeClaude.cs``);
#. install VS Code and its extensions at pinned versions
   (``vscode-sbom.pcs``);
#. bring it all together as one BISOS capability
   (``vscodeClaude-cbs.pcs``, a CBM leaf).

The core of PyCS-Framework is the *bisos.b* package (the
PyCS-Foundation). See `bisos.b <https://github.com/bisos-pip/b>`__ for
an overview.

Installation
============

The sources for the bisos.vscodeClaude pip package are maintained at:
https://github.com/bisos-pip/vscodeClaude.

Installation With pip
---------------------

.. code:: bash

   pip install bisos.vscodeClaude

On a BISOS host, install it editable from its source, in ``py3/``:

.. code:: bash

   ./pypiProc.sh -v -n showRun -i pkgReInstall edit /bisos/venv/bisos3

Installation With pipx
----------------------

.. code:: bash

   pipx install bisos.vscodeClaude

The following commands are made available:

-  ``vscode.cs``
-  ``vscodeClaude.cs``
-  ``vscode-sbom.pcs``
-  ``vscodeClaude-cbs.pcs``, ``vscodeClaude-assemble.cs``

Installing VS Code and Its Extensions: ``vscode-sbom.pcs``
----------------------------------------------------------

``vscode-sbom.pcs`` installs VS Code itself from Microsoft's apt
repository, and the extensions of the local VS Code, per user, at pinned
versions: among them ``anthropic.claude-code`` (the Claude panel, whose
``/open`` URI is the prompt channel) and the Emacs keymap and org-mode
extensions.

::

   vscode-sbom.pcs -i aptPkgs_update all     # VS Code (code) from packages.microsoft.com
   vscode-sbom.pcs -i codeReport             # VS Code installed vs candidate, pinned and minimum
   vscode-sbom.pcs -i codeInstallPinned      # VS Code at the pinned version (sudo; may downgrade)
   vscode-sbom.pcs -i codeInstallLatest      # VS Code installed, or upgraded, to the latest
   vscode-sbom.pcs -i extsReport            # the pinned versions against the installed ones
   vscode-sbom.pcs -i extsInstallPinned      # install at the pinned versions (as the VS Code user)
   vscode-sbom.pcs -i extsInstallLatest      # install, or upgrade, to the latest versions

All at Once: the vscodeClaude Capability (CBS and CBM)
------------------------------------------------------

``vscodeClaude-cbs.pcs`` is the Capability Bundle Specification of the
whole setup, of type ``induct`` (an install, no service): its sbom is
``vscode-sbom.pcs`` (VS Code, through sudo), and its assemble,
``vscodeClaude-assemble.cs``, sets up the invoking user: the extensions
at their pinned versions (``extensions``), the VS Code to Blee link
(``bleeLink``, ``vscodeBleeLinkInstall``) and the Claude Code hooks to
Blee (``hooks``, ``hooksInstall``). The assemble steps are per user and
refuse to run as root.

::

   vscodeClaude-assemble.cs -i fullCheck      # read-only: extensions, the Blee link, the hooks
   vscodeClaude-cbs.pcs -i cbs_materialize    # the sbom, then fullUpdate (as the VS Code user)

Its CBM leaf, a pointer to this CBS gated by ``cbmProc.control``
(planted ``available``), is
``/bisos/platform/sys/cbm/collective/induct/vscodeClaude/cbmProc.spcs``:

::

   cbmProc.spcs -i cbm_enable && cbmProc.spcs -i cbm_materialize

The Blee side, the vscode-claude Blee package, comes with Blee.

Usage
=====

Each command program is a small CSXU over its CSUs, whose examples it
shows: ``vscode.cs`` with no arguments lists its examples, and so does
``vscodeClaude.cs``.

VS Code Itself: ``vscode.cs``
-----------------------------

Layer 2, ``vscode_csu``: no Emacs, no Claude.

+----------------------------+----------------------------------------+
| Command                    | What it does                           |
+============================+========================================+
| ``vscodeVersion``          | version, commit, architecture          |
+----------------------------+----------------------------------------+
| ``vscodeTopology``         | can this shell reach a desktop VS      |
|                            | Code, on which ``DISPLAY``             |
+----------------------------+----------------------------------------+
| ``vscodeWorkspaces``       | the folders VS Code has state for,     |
|                            | newest first (a history)               |
+----------------------------+----------------------------------------+
| ``vscodeWindows``          | the open windows: each folder as       |
|                            | opened, and its true name              |
+----------------------------+----------------------------------------+
| ``vscodeExtensions``       | the installed extensions (installing   |
|                            | them: ``vscode-sbom.pcs``)             |
+----------------------------+----------------------------------------+
| ``vscodeExtensionVersion`` | one extension's version, e.g.          |
|                            | ``anthropic.claude-code``              |
+----------------------------+----------------------------------------+
| ``vscodeFocus``            | bring a window to the front, by its    |
|                            | folder's name                          |
+----------------------------+----------------------------------------+
| ``vscodeOpenFile``         | a file, at a line and column           |
+----------------------------+----------------------------------------+
| ``vscodeOpenFolder``       | a folder: its open window, else a new  |
|                            | one (``--window=``)                    |
+----------------------------+----------------------------------------+
| ``vscodeAddFolder``        | add a folder to the current window's   |
|                            | workspace                              |
+----------------------------+----------------------------------------+
| ``vscodeDiff``             | the diff view of two files             |
+----------------------------+----------------------------------------+
| ``vscodeOpenUri``          | hand a URI to the desktop VS Code      |
|                            | (``code --open-url``)                  |
+----------------------------+----------------------------------------+

::

   vscode.cs -i vscodeTopology
   vscode.cs -i vscodeOpenFile README.org 40 1

VS Code and Its Partner Emacs: ``vscode.cs``
--------------------------------------------

Layer 3, ``vscodeEmacs_csu``, in the same command program: no Claude.

+---------------------------+-----------------------------------------+
| Command                   | What it does                            |
+===========================+=========================================+
| ``vscodePartner``         | the partner Emacs (Blee), or why there  |
|                           | is none                                 |
+---------------------------+-----------------------------------------+
| ``bleeOpenFile``          | a file in the partner Emacs, at a line  |
|                           | (VS Code to Emacs)                      |
+---------------------------+-----------------------------------------+
| ``vscodeBleeLinkSnippet`` | the VS Code task and key that run       |
|                           | ``bleeOpenFile``, to paste              |
+---------------------------+-----------------------------------------+
| ``vscodeBleeLinkCheck``   | read-only: are the task, key and        |
|                           | setting in VS Code's files              |
+---------------------------+-----------------------------------------+
| ``vscodeBleeLinkInstall`` | merge them into VS Code's user files    |
|                           | (idempotent, backups)                   |
+---------------------------+-----------------------------------------+
| ``bleeMagit``             | a repo's magit status in the partner    |
|                           | Emacs (a commit walk)                   |
+---------------------------+-----------------------------------------+

**The partner Emacs is optional.** These commands, and ``hookToEmacs``
below, read the partner file that Blee's ``b:vscode/init`` writes
(``/bisos/var/blee/vscode/partner-<user>.json``): one Emacs partners
with one VS Code. A partner is live only if its pid is a running Emacs
and its socket exists.

**Per-user setup, after ``vscode-sbom.pcs``.** The VS Code to Emacs key
is set up by ``vscode.cs -i vscodeBleeLinkInstall`` (and the hooks below
by ``vscodeClaude.cs -i hooksInstall``). They merge into the user's own
files, keep everything else, back each file up, and change nothing when
run again. VS Code's files may hold comments: a comment block before the
JSON is kept; a file with comments inside is refused, and its piece is
added by hand (``...Snippet`` prints it).

For ``/bx-git-commit-walk`` to open each repo in Blee, set aiActivity's
``gitOpener``:

::

   aiActivity.cs -i userConfig_set --parName=gitOpener --parValue='vscode.cs -i bleeMagit'

Its Claude Sessions: ``vscodeClaude.cs``
----------------------------------------

Layer 4, ``vscodeClaude_csu``, over the two above.

+--------------------------+------------------------------------------+
| Command                  | What it does                             |
+==========================+==========================================+
| ``claudeSessionsList``   | the running sessions, one line each,     |
|                          | newest first                             |
+--------------------------+------------------------------------------+
| ``claudeSessionsLatest`` | the sessionId of the most recently       |
|                          | active local session                     |
+--------------------------+------------------------------------------+
| ``claudePromptUri``      | the URI ``claudePrompt`` would use;      |
|                          | sends nothing                            |
+--------------------------+------------------------------------------+
| ``claudePrompt``         | the prompt into the latest session, a    |
|                          | given one, or a new one                  |
+--------------------------+------------------------------------------+
| ``hookToEmacs``          | a Claude Code hook: the event to the     |
|                          | partner Emacs, if any                    |
+--------------------------+------------------------------------------+
| ``hooksSnippet``         | the ``~/.claude/settings.json`` hooks    |
|                          | entry for ``hookToEmacs``                |
+--------------------------+------------------------------------------+
| ``hooksCheck``           | read-only: are those hooks in            |
|                          | ``~/.claude/settings.json``              |
+--------------------------+------------------------------------------+
| ``hooksInstall``         | merge them into it (idempotent, a backup |
|                          | first)                                   |
+--------------------------+------------------------------------------+

``claudeSessionsList`` takes ``--mode`` (local, remote, all) and
``--cwd``; ``claudePrompt`` takes ``--session`` (an id, or ``new``),
``--cwd``, ``--folder`` (first bring forward that folder's window, else
open one: a new conversation then starts there), and ``--submit=yes`` to
press Enter as well (default: you do).

``vscodeOpenFolder --window=focus`` (the default) brings forward the
window that already has the folder, else opens it in a new window;
``new`` always opens one; ``reuse`` puts it in the last active window,
replacing that window's folder (the window reloads, its Claude sessions
end). VS Code matches a folder by the spelling it was opened with
(``/bxRepos/x`` and its true name are two folders to it): ``focus``
finds the open window by true name, from VS Code's ``storage.json``, and
passes its spelling.

::

   vscodeClaude.cs -i claudeSessionsList
   DISPLAY=:1 vscodeClaude.cs -i claudePrompt "/bx-git-commit-msg ."

``claudePrompt`` opens the session through the Claude extension's URI
handler (``code --open-url``), so it needs the ``DISPLAY`` of the
desktop VS Code. A session that is already open only comes to the front
that way, so for a running session the text goes on the X clipboard
(``xclip``) and is pasted with ``xdotool``. Each command it runs is
shown on stderr.

With no live partner, ``hookToEmacs`` does nothing, at once and
silently, so installing the hooks does not affect pure VS Code use.

Both the session list (Claude Code's ``~/.claude/sessions/``) and the
URI handler are undocumented Claude Code internals, read as they are in
Claude Code 2.1.311; an upgrade may change them.

The Emacs Layer: vscode-claude
------------------------------

For those who work in Emacs, the Blee package
`vscode-claude <https://github.com/bx-blee/vscode-claude>`__ is layered
over this one: ``b:vscode.el`` over ``vscode.cs``,
``b:vscode:claude.el`` (prompts, sessions, hooks) over
``vscodeClaude.cs``, and ``b:vscode:claude:aiActivity.el`` (root and
here, the commit cycle, the commit walk) over that. It is optional and
does not interfere with pure VS Code use. Its README has the design: the
partnership, the sessions and their AI-Activities, the channels in both
directions, and the figure of the layers.

Key Files
=========

+----------------------------------+----------------------------------+
| File, in ``py3/``                | What                             |
+==================================+==================================+
| ``bin/vscode.cs``                | CSXU over ``vscode_csu`` and     |
|                                  | ``vscodeEmacs_csu``              |
+----------------------------------+----------------------------------+
| ``bin/vscodeClaude.cs``          | CSXU over ``vscodeClaude_csu``   |
|                                  | (was ``claudeSessions.cs``)      |
+----------------------------------+----------------------------------+
| ``bin/vscode-sbom.pcs``          | VS Code and its extensions,      |
|                                  | pinned                           |
+----------------------------------+----------------------------------+
| ``bin/vscodeClaude-cbs.pcs``     | the capability: the sbom, then   |
|                                  | the assemble                     |
+----------------------------------+----------------------------------+
| ``bin/vscodeClaude-assemble.cs`` | per user: extensions, the Blee   |
|                                  | link, the hooks                  |
+----------------------------------+----------------------------------+
| ``bi                             | layer 2: VS Code itself; the     |
| sos/vscodeClaude/vscode_csu.py`` | ``xclip`` and ``xdotool``        |
|                                  | helpers                          |
+----------------------------------+----------------------------------+
| ``bisos/v                        | layer 3: the partner file,       |
| scodeClaude/vscodeEmacs_csu.py`` | ``emacsclient``                  |
+----------------------------------+----------------------------------+
| ``bisos/vs                       | layer 4: the session registry,   |
| codeClaude/vscodeClaude_csu.py`` | the ``/open`` URI, hooks         |
+----------------------------------+----------------------------------+

-  ``vscode_csu.py`` inspects the local VS Code (its processes and
   ``DISPLAY``, the workspaces it keeps state for in its undocumented
   ``workspaceStorage/``, its extensions) and opens things in it.
-  ``vscodeEmacs_csu.py`` reads the partner file and evaluates in the
   partner Emacs.
-  ``vscodeClaude_csu.py`` reads the session registry, builds the
   extension's ``/open`` URI, prompts, and relays hook events.

All bisos-pip repos in the https://github.com/bisos-pip github
organization follow the same structure. They all have
`setup.py <./setup.py>`__ files driven by
`pypiProc.sh <./pypiProc.sh>`__.

Documentation and Blee-Panels
=============================

bisos.vscodeClaude is part of ByStar Digital Ecosystem
http://www.by-star.net.

Its Blee-Panel is
`file:./panels/bisos.vscodeClaude/_nodeBase_/fullUsagePanel-en.org <./panels/bisos.vscodeClaude/_nodeBase_/fullUsagePanel-en.org>`__;
in Blee it is under
``/bisos/panels/bisos-core/bisos-pip/bisos.vscodeClaude``. It has a
section per command program and layer, with the read-only commands'
output and buttons for the actions.

Testing
=======

``py3/tests/verify.sh`` runs every read-only command from PATH. It
opens, focuses or prompts nothing in VS Code, and reaches no partner
Emacs: ``hookToEmacs`` runs as a made-up user, with a missing and then a
stale partner file.

::

   cd py3/tests && bash -i ./verify.sh

Support
=======

| For support, criticism, comments and questions; please contact the
  author/maintainer
| `Mohsen Banan <http://mohsen.1.banan.byname.net>`__ at:
  http://mohsen.1.banan.byname.net/contact

Planned Improvements
====================

-  Upload to PyPI and test as pipx install.
