PG-CS-001 · IT HELP · CODESENTINEL · GUIDE
CodeSentinel Getting Started
Start from the current public GitHub source, understand how it differs from PyPI, and run only bounded first inspections.
CodeSentinel is a repository maintenance and security-monitoring tool. This page orients a new reader to the current public source repository, the command families exposed by that source, a bounded first inspection, and the decision point before configuration, scheduling, cleanup, integrity baselines, or agent-assisted development work.
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.
1What You Are Running Core
CodeSentinel has two public faces. The public GitHub repository is the current source surface. PyPI is the packaged install surface. They are not currently the same version, so a reader should ask three separate questions before following a command example:
- Source identity: Which public repository and branch is this guide describing?
- Install identity: Which package version is actually installed in the active environment?
- Command authority: Is the command backed by the current public source parser?
2Before the First Command Core
Run first commands in a repository where you have authority to inspect the files and where the current state can be recovered. CodeSentinel is a maintenance tool, not just a passive viewer. Even status and scan workflows should be treated as operational activity.
- Know the repository owner, branch, and current worktree state.
- Keep private paths, credentials, webhooks, and tokens out of examples and retained output.
- Separate observation from permission to change files, schedule tasks, or create baselines.
- Stop before cleanup, configuration, scheduling, integrity reset, or agent remediation unless that workflow is approved.
3Confirm the Public Source Core
This guide assumes a checkout of the public repository. The commands below identify the public source and declared package metadata; detailed environment creation and repair stay on the installation page.
git clone https://github.com/joediggidyyy/CodeSentinel.git
cd CodeSentinel
git status -sb
In pyproject.toml, the reviewed public source declares version
1.1.3.b1. If your checkout differs from the current public branch, treat the
page as a model and verify the changed parser before relying on command details.
4Orient to the CLI Core
After installing from the source checkout, begin with help and status. These commands orient the interface; they do not grant permission to run cleanup, scheduling, update, integrity, or agent-assisted workflows.
python -m codesentinel.cli --help
python -m codesentinel.cli status
Prefer python -m codesentinel.cli while checking a source checkout. It makes
the active source path clearer than a shell launcher that may point at an older package
install.
5Public-Source Command Families Core
Top-level parser registration means a family is exposed by the public source. It does not prove every subcommand is configured, appropriate for your repository, or safe to run without review.
| Family | Primary purpose | Side-effect class | Treatment here |
|---|---|---|---|
| status | Summarize configuration and system state | Observation with runtime supervision | Core orientation |
| scan | Run security or repository-bloat inspections | Analysis; may emit structured output | Core bounded inspection |
| maintenance | Run daily, weekly, or monthly upkeep workflows | Repository maintenance | Follow-on only |
| clean | Archive or remove selected repository artifacts | Mutation, even with archive-first policy | Follow-on only |
| index | Build, validate, or sync documentation indices | Generated metadata | Follow-on only |
| docs | Search or validate documentation surfaces | Observation or validation | Follow-on only |
| alert | Configure or send alerts | Configuration or notification | Use only as alert send or alert config after review |
| schedule | Manage the maintenance scheduler | Background activity | Follow-on only |
| venv | Manage CodeSentinel virtual environments | Environment creation or archival | Installation-page detail |
| update | Update docs, changelog, version, or related metadata | Repository mutation | Follow-on only |
| integrate | Connect commands into workflows | Workflow mutation | Follow-on only |
| test | Run beta or validation workflows | Test execution | Follow-on only |
| setup | Run setup wizard behavior | Configuration | Installation-page detail |
| dev-audit | Run development audit workflows | Analysis; optional remediation modes | Advanced/development only |
| integrity | Manage file-integrity monitoring | Baseline and verification state | Advanced only |
| memory | Manage session memory and process context | Operational state | Follow-on only |
6First Bounded Inspection Core
A bloat audit is a useful first inspection because it asks CodeSentinel to observe and report before you decide whether any cleanup is justified. Run it only in an authorized repository and preserve output with care because file names and paths can disclose private project structure.
python -m codesentinel.cli scan --bloat-audit --json| Command | Can establish | Cannot establish | Next decision |
|---|---|---|---|
| git status -sb | Which branch and worktree state you are using | Whether installed launchers point at that source | Confirm you are on the intended public source branch |
| python -m codesentinel.cli --help | Visible command families for the active source path | Whether every workflow is configured or safe for your repository | Choose only an authorized family |
| scan --bloat-audit --json | Structured observations about repository bloat candidates | Permission to delete, archive, reorganize, or ignore evidence | Review output before any cleanup |
7Read the Result Before Acting Core
Treat scan output as evidence to review, not authority to change the repository. A finding can be correct, stale, incomplete, irrelevant to your goal, or blocked by missing context. Keep the distinction clear:
- Observation: what the tool saw in the current workspace.
- Severity: how important the tool believes the observation may be.
- Recommendation: a possible response, not a mandate.
- Authority: the separate permission to change, archive, schedule, or notify.
8Choose the Next Workflow Core
After the first inspection, pick the next workflow by goal. Do not move from a scan result directly into cleanup or automation just because the CLI exposes those commands.
| Goal | Do next |
|---|---|
| Set up or fix your environment | Use the installation guide before running more commands. |
| Review scan output responsibly | Retain JSON carefully and redact repository-sensitive paths before sharing. |
| Plan cleanup | Decide scope, archive policy, and recovery before running clean commands. |
| Add scheduling or alerts | Review background activity, credentials, and notification targets first. |
| Set up integrity monitoring | Use the advanced baseline model in section 10 before creating or replacing a baseline. |
9Advanced: Structured Scan Evidence Optional advanced
Structured output is useful when you need to compare scans, attach evidence to a ticket, or preserve a before-and-after record. It is also easy to overshare. Treat file paths, project names, timestamps, and generated recommendations as repository-sensitive data.
Retained evidence is only as trustworthy as the same four-part read from section 7 that you applied when you first reviewed it. Preserve all four, not only the observation:
| Framework element | What retained evidence must also capture |
|---|---|
| Observation | Source checkout, command, repository, and the time it ran -- an observation without provenance cannot be trusted later. |
| Severity | The severity as reported at that moment; tool logic can change between versions, so do not silently treat old evidence as current. |
| Recommendation | The recommendation text as given -- useful for showing what advice existed, not proof that it was followed. |
| Authority | Who reviewed the evidence and approved any resulting action -- retained evidence is not itself authorization. |
Compare two pieces of evidence by question and scope, not only by a change in count. A difference is not automatic causation -- changed inputs, environment, ignored files, or parser changes can also explain it. Keep agent-assisted remediation outside this tutorial.
10Advanced: Integrity as a Deliberate Baseline Optional advanced
Integrity commands are not just status checks. A baseline records what the system should compare against later. Creating, resetting, or widening that baseline can redefine what future verification treats as normal.
| State or action | Effect | Authority requirement | Recovery consideration |
|---|---|---|---|
| status | Reports whether integrity monitoring is configured or active | Repository inspection authority | Does not prove the baseline is correct |
| start | Enables monitoring behavior | Operational approval | Know where state and logs are written |
| verify | Compares current files against a baseline | Inspection authority and baseline trust | Review drift before acting |
| config baseline | Creates or replaces expected file state | Explicit baseline approval | Preserve prior baseline or commit state first |
| reset or whitelist | Changes what future checks consider acceptable | Owner-level approval | Document why the change is legitimate |
References
- [1] Public CodeSentinel repository. GitHub repository for the current public source boundary.
- [2] Public README. CodeSentinel README on GitHub.
- [3] Public package metadata. pyproject.toml on GitHub.
- [4] Public CLI source. codesentinel CLI parser source on GitHub.
- [5] PyPI package page. Installable CodeSentinel package surface.
- [6] Installation follow-up. CodeSentinel installation guide.
- [7] Technical background. CodeSentinel technical report.