PG-CS-002 · IT HELP · CODESENTINEL · INSTALLATION GUIDE
CodeSentinel Installation
Choose the installation form that matches the artifact, environment, and maintenance role—then verify exactly what is active.
CodeSentinel can be installed from the Python Package Index, a public source checkout, a release artifact, or a complete offline wheelhouse. Choose one path for the machine you are preparing. Each path below includes its own commands, identity checks, and troubleshooting handoff; you do not need to perform all eight.
Tooling disclosure. This guide was developed using a repository governance harness and AI-assisted research/curation workflow engineered by Joe Waller and enabled through OpenAI and Anthropic tooling. These tools support research and documentation, including source review, summarization, validation, and guide drafting, and do not replace the author's judgment.
1Choose an Installation Path Core
Begin with the artifact you possess and the way the environment will be maintained. The selector does not rank one supported path as more legitimate than another; it identifies the procedure that fits the situation.
Text equivalent: with PyPI access, choose IV-01 for an isolated environment or IV-02 when only a user-site install is available. With a checkout, choose IV-03 for an installed snapshot or IV-04 for an editable worktree. With a published artifact, choose IV-05 for a direct wheel URL, IV-06 for a wheel already downloaded, or IV-07 for a source archive. Without index access, choose IV-08 and use a complete wheelhouse or supplied offline helper.
| Path | Artifact source | Index or network | Checkout behavior | Best fit |
|---|---|---|---|---|
| IV-01 | PyPI | Package index | None | Ordinary isolated use |
| IV-02 | PyPI | Package index | None | User-site installation |
| IV-03 | Cloned source | Git access | Installed snapshot | Source-based use |
| IV-04 | Cloned source | Git access | Editable worktree | Contribution and testing |
| IV-05 | Release wheel URL | GitHub release access | None | Specific remote artifact |
| IV-06 | Downloaded wheel | No index required | None | Known local artifact |
| IV-07 | Source archive | No index for the project artifact | Temporary extracted source | Downloaded source distribution |
| IV-08 | Offline wheelhouse or bundle | No network | None | Disconnected installation |
2Shared Preflight Core
Confirm the selected interpreter before installing. The PyPI path needs Python 3.13 or newer; the source snapshot described here declares Python 3.8 or newer. Prefer a fresh project-local environment so the imported package can be identified without ambiguity.
py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python --versionpy -3.13 -m venv .venv
.venv\Scripts\activate.bat
python -m pip install --upgrade pip
python --versionpython3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python --version3PyPI Installation Paths Choose one
IV-01 · PyPI in an Isolated Virtual Environment
Use this path for ordinary package use. Complete the matching environment-activation procedure in Section 2, install inside that environment, and then run all four checks.
python -m pip install codesentinel
python -m pip show codesentinel
python -c "import codesentinel; print(codesentinel.__file__)"
codesentinel --help
codesentinel statusIV-02 · PyPI User-Site Installation
Use this path when an isolated environment cannot be created or written. It shares the user account's package area and may place the command outside the current PATH, so identify the user base before diagnosing a missing command.
python -m pip install --user codesentinel
python -m site --user-base
python -m pip show codesentinel
python -c "import codesentinel; print(codesentinel.__file__)"
codesentinel --help
codesentinel status4Source Checkout Paths Choose one
IV-03 · Standard Installation from a Cloned Checkout
Use the standard source path when the public checkout is the artifact source but edits in that checkout should not immediately change the installed package. Create and activate an environment as shown in Section 2 before running this cell.
git clone https://github.com/joediggidyyy/CodeSentinel.git
cd CodeSentinel
python -m pip install .
python -m pip show codesentinel
python -c "import codesentinel; print(codesentinel.__file__)"
codesentinel --help
codesentinel statusThe printed import path should be inside the active environment rather than resolving directly to the checkout.
IV-04 · Editable Installation from a Cloned Checkout
Use the editable path for authorized contribution or source testing. Create and activate an environment as shown in Section 2; changes in the checkout then affect the active environment.
git clone https://github.com/joediggidyyy/CodeSentinel.git
cd CodeSentinel
python -m pip install -e .
python -m pip show codesentinel
python -c "import codesentinel; print(codesentinel.__file__)"
codesentinel --help
codesentinel status5Release Artifact Paths Choose one
IV-05 · Direct Installation from a GitHub Release Wheel
Open the public release page, choose a compatible wheel, and copy its asset URL. Replace both bracketed names below with values from that release; they are not literal package names.
python -m pip install "https://github.com/joediggidyyy/CodeSentinel/releases/download/<release-tag>/<wheel-file>.whl"
python -m pip show codesentinel
python -c "import codesentinel; print(codesentinel.__file__)"
codesentinel --help
codesentinel statusIV-06 · Installation from a Downloaded Local Wheel
Use this path when the selected wheel is already on the machine. Activate the target environment and supply the actual local wheel path.
python -m pip install <path-to-wheel>
python -m pip show codesentinel
python -c "import codesentinel; print(codesentinel.__file__)"
codesentinel --help
codesentinel statusIV-07 · Installation from a Source-Distribution Archive
A source distribution can be installed directly, or extracted and installed from its root. Activate the target environment first. Dependencies still need to be available unless the installation is paired with a complete offline wheelhouse.
python -m pip install <path-to-source-archive.tar.gz>
python -m pip show codesentinel
python -c "import codesentinel; print(codesentinel.__file__)"
codesentinel --help
codesentinel statustar -xf <path-to-source-archive.tar.gz>
cd <extracted-source-directory>
python -m pip install .
python -m pip show codesentinel
python -c "import codesentinel; print(codesentinel.__file__)"
codesentinel --help
codesentinel status6Offline Installation IV-08
The wheelhouse must contain the CodeSentinel wheel and every required dependency wheel. Use a dedicated environment and confirm that the wheels match the target operating system, architecture, interpreter implementation, and Python minor version.
python -m pip install --no-index --find-links ./wheels ./wheels/codesentinel-<version>-py3-none-any.whl
python -m pip show codesentinel
python -c "import codesentinel; print(codesentinel.__file__)"
codesentinel --help
codesentinel status
When the supplied offline archive contains install_offline.ps1, running
that helper from the extracted bundle root is an equal supported route:
.\install_offline.ps17Verify the Active Artifact Core
Run the same four checks after every path. Package metadata identifies the installed distribution; the import path shows which files Python loads; the two CLI checks prove that the command surface is available.
python -m pip show codesentinel
python -c "import codesentinel; print(codesentinel.__file__)"
codesentinel --help
codesentinel status| Installed form | Expected import location | Meaning |
|---|---|---|
| PyPI, wheel, archive, or standard source | Inside the active environment | The environment imports an installed artifact. |
| Editable source | The selected checkout | The environment follows that worktree. |
| Unexpected location | Another environment or checkout | Stop and correct interpreter or activation selection. |
8Upgrade, Refresh, Reinstall, and Uninstall
Run lifecycle commands only after activating the environment that contains the installation. Re-run the shared verification sequence after an upgrade, refresh, or reinstall.
LC-01 · Upgrade a PyPI Installation
Use this when the active environment already has a PyPI install and you want the newest version on that same path. Activate the environment first; upgrading does not switch install paths on its own.
python -m pip install --upgrade codesentinelLC-02 · Refresh a Standard Source Installation
Use this after pulling new commits into a standard (non-editable) source checkout. A
plain git pull does not update the installed package by itself; the
install step must be re-run to pick up the change.
git pull
python -m pip install --upgrade .LC-03 · Refresh an Editable Source Installation
An editable install already tracks the checkout for Python source changes, but pulling changes to build metadata or entry points still needs the editable install step re-run to take effect.
git pull
python -m pip install --upgrade -e .LC-04 · Force Reinstall the Selected Artifact
Use this to recover from a corrupted or partially-installed package without first uninstalling. pip reinstalls every file for the named artifact even if it believes the version is already satisfied.
python -m pip install --force-reinstall <selected-package-or-artifact>LC-05 · Uninstall CodeSentinel
Use this to remove the package entirely from the active environment.
python -m pip uninstall codesentinelUninstallation removes the package from the active environment. It does not automatically delete configuration files stored in project directories.
9Troubleshooting
| Symptom | Likely cause | Evidence command | Bounded correction |
|---|---|---|---|
| Python version rejected | The interpreter does not satisfy the selected artifact. | python --version | Create a new environment with a supported interpreter. |
| Command not found after user-site install | The user scripts directory is not on PATH. | python -m site --user-base | Add that user's scripts directory to the current shell PATH. |
| Import and pip disagree | pip and Python point at different environments. | python -m pip --version | Reactivate the intended environment and use python -m pip. |
| Editable changes have no effect | The active import is not the intended checkout. | python -c "import codesentinel; print(codesentinel.__file__)" | Activate the correct environment or reinstall that checkout with -e. |
| No matching wheel | OS, architecture, interpreter, or Python minor version is incompatible. | python -m pip debug --verbose | Select or rebuild a compatible wheel; do not force an incompatible artifact. |
| Offline dependency missing | The wheelhouse is incomplete. | Inspect the supplied wheels directory. | Obtain a complete bundle containing every dependency wheel. |
| Wrong active artifact | Another environment or checkout is earlier on the import path. | Run all four shared verification commands. | Stop, select the intended environment, and repeat the chosen installation path. |
10Next Step
Installation is complete when the selected artifact imports from the expected location and both CLI checks succeed. Continue with CodeSentinel Getting Started for orientation, bounded first commands, and the decision point before configuration.