{"id":51167611,"url":"https://github.com/stef-k/agent-loc-guard","last_synced_at":"2026-06-26T21:01:11.472Z","repository":{"id":358409339,"uuid":"1241300323","full_name":"stef-k/agent-loc-guard","owner":"stef-k","description":"Cross-agent LOC guard skill for Codex and Claude Code","archived":false,"fork":false,"pushed_at":"2026-05-17T07:58:28.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T09:41:59.551Z","etag":null,"topics":["agent-skills","ai-coding-agent","claude-skills","code-quality","codex-skills","loc-checker","source-file-size"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stef-k.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-17T07:52:03.000Z","updated_at":"2026-05-17T07:56:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stef-k/agent-loc-guard","commit_stats":null,"previous_names":["stef-k/agent-loc-guard"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/stef-k/agent-loc-guard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef-k%2Fagent-loc-guard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef-k%2Fagent-loc-guard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef-k%2Fagent-loc-guard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef-k%2Fagent-loc-guard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stef-k","download_url":"https://codeload.github.com/stef-k/agent-loc-guard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef-k%2Fagent-loc-guard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34832916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-coding-agent","claude-skills","code-quality","codex-skills","loc-checker","source-file-size"],"created_at":"2026-06-26T21:01:10.144Z","updated_at":"2026-06-26T21:01:11.439Z","avatar_url":"https://github.com/stef-k.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent LOC Guard\n\nAgent LOC Guard is a small, portable file-length guard for agent-assisted development.\n\nIt combines:\n\n- a deterministic Python LOC checker;\n- an agent skill (`SKILL.md`);\n- a reusable policy reference;\n- example Codex and Claude integration files;\n- a GitHub Actions workflow example.\n\nThe goal is not to force tiny files. The goal is to stop agents from producing oversized, hard-to-review files without judgment.\n\n## Packaging choice\n\nUse this project as a cross-agent skill/tool.\n\nThe canonical pieces are:\n\n- `skills/loc-guard/SKILL.md` for agent behavior;\n- `skills/loc-guard/references/loc-policy.md` for reusable policy text;\n- `skills/loc-guard/scripts/loc_guard.py` for deterministic checking;\n- `examples/loc-guard.config.json` for project-local thresholds and excludes.\n\n## Policy summary\n\n- `400` counted LOC is a review trigger, not an automatic refactor command.\n- `600` counted LOC is a hard cap unless the user explicitly approves an exception.\n- A warning requires the agent to inspect cohesion, responsibility boundaries, and likely near-term growth.\n- A split should happen only when it improves boundaries or reduces meaningful complexity.\n\nRequired warning report:\n\n```text\nwarning accepted with justification: ...\n```\n\nor:\n\n```text\nsplit performed because: ...\n```\n\n## Recommended repo layout\n\nCopy the package into a project like this:\n\n```text\n.agent-tools/\n  loc_guard.py\n  loc-guard.config.json\n\n.agent-skills/\n  loc-guard/\n    SKILL.md\n    references/\n      loc-policy.md\n\nAGENTS.md\nCLAUDE.md\n```\n\nFor a simple installation, copy:\n\n```text\nskills/loc-guard/scripts/loc_guard.py\n```\n\nto:\n\n```text\n.agent-tools/loc_guard.py\n```\n\nand copy:\n\n```text\nexamples/loc-guard.config.json\n```\n\nto:\n\n```text\n.agent-tools/loc-guard.config.json\n```\n\nMinimal project install from a checkout of this repository:\n\n```bash\nmkdir -p .agent-tools .agent-skills\ncp skills/loc-guard/scripts/loc_guard.py .agent-tools/loc_guard.py\ncp examples/loc-guard.config.json .agent-tools/loc-guard.config.json\ncp -R skills/loc-guard .agent-skills/loc-guard\n```\n\nCopy the skill directory when the target agent supports project skills:\n\n```bash\nmkdir -p .agent-skills\ncp -R skills/loc-guard .agent-skills/loc-guard\n```\n\nFor agents that do not have a skill loader, copy the policy block from `examples/AGENTS.md` or `examples/CLAUDE.md` into the agent instruction file and keep the checker under `.agent-tools/`.\n\n## Codex installation\n\nAfter this repository is published, Codex users can install the skill directly from GitHub:\n\n```text\nUse $skill-installer to install https://github.com/stef-k/agent-loc-guard/tree/main/skills/loc-guard\n```\n\nFor project-local use, also copy the checker and config:\n\n```bash\nmkdir -p .agent-tools\ncp skills/loc-guard/scripts/loc_guard.py .agent-tools/loc_guard.py\ncp examples/loc-guard.config.json .agent-tools/loc-guard.config.json\n```\n\n## Claude Code installation\n\nClaude Code supports the same `SKILL.md` format, but uses Claude-specific install locations.\n\nPersonal install:\n\n```bash\nmkdir -p ~/.claude/skills\ncp -R skills/loc-guard ~/.claude/skills/loc-guard\n```\n\nProject install:\n\n```bash\nmkdir -p .claude/skills\ncp -R skills/loc-guard .claude/skills/loc-guard\n```\n\nProject hook install:\n\n```bash\nmkdir -p .claude .agent-tools\ncp hooks/claude/settings.example.json .claude/settings.json\ncp skills/loc-guard/scripts/loc_guard.py .agent-tools/loc_guard.py\ncp examples/loc-guard.config.json .agent-tools/loc-guard.config.json\n```\n\nClaude discovers personal skills from `~/.claude/skills/\u003cskill-name\u003e/SKILL.md` and project skills from `.claude/skills/\u003cskill-name\u003e/SKILL.md`. The Codex-only `skills/loc-guard/agents/openai.yaml` file is harmless for Claude but is not used for Claude discovery.\n\n## Discovery and installation\n\nFor users, describe this package with these search terms wherever it is published:\n\n```text\nagent loc guard, agent file length policy, AI coding guardrail, Codex skill, Claude skill, source file size checker\n```\n\nFor installed agents, discovery comes from:\n\n- the skill metadata in `skills/loc-guard/SKILL.md`;\n- the UI metadata in `skills/loc-guard/agents/openai.yaml`;\n- the instruction snippets in `examples/AGENTS.md` and `examples/CLAUDE.md`;\n- hook examples under `hooks/` for automatic checks after edits.\n\nSuggested installation modes:\n\n- **Project-local**: copy `.agent-tools/`, `.agent-skills/`, and instruction snippets into each repository that wants enforcement.\n- **Personal agent skill**: install `skills/loc-guard/` into the agent's personal skills directory and copy `loc_guard.py` into each checked project.\n- **CI visibility**: copy `ci/github/loc-guard.yml` into `.github/workflows/loc-guard.yml` so users see policy failures in pull requests.\n\nVerify an install with:\n\n```bash\npython3 .agent-tools/loc_guard.py . --config .agent-tools/loc-guard.config.json\n```\n\nPublishing checklist:\n\n- Keep the repository name and package title as `agent-loc-guard`.\n- Keep the first README paragraph focused on agent-assisted coding and file length policy.\n- Add repository topics matching the search terms above.\n- Include `skills/loc-guard/agents/openai.yaml` in published packages for Codex UI discovery.\n- Keep `examples/AGENTS.md` and `examples/CLAUDE.md` short so users can paste them directly.\n- Tag releases when the checker behavior or policy text changes.\n\n## Usage\n\nRun from the root of a repository:\n\n```bash\npython3 .agent-tools/loc_guard.py .\n```\n\nUse an explicit config:\n\n```bash\npython3 .agent-tools/loc_guard.py . --config .agent-tools/loc-guard.config.json\n```\n\nCheck only changed files:\n\n```bash\npython3 .agent-tools/loc_guard.py . --changed-only\n```\n\nCheck staged files before commit:\n\n```bash\npython3 .agent-tools/loc_guard.py . --staged\n```\n\nEmit JSON:\n\n```bash\npython3 .agent-tools/loc_guard.py . --json\n```\n\nOverride thresholds:\n\n```bash\npython3 .agent-tools/loc_guard.py . --warn 400 --fail 600\n```\n\n## Exit codes\n\n```text\n0 = OK\n1 = one or more warning-threshold files found\n2 = one or more hard-fail files found\n3 = tool/configuration/runtime error\n```\n\nHard failures take precedence over warnings.\n\n## Counted LOC\n\nBy default, counted LOC means non-blank physical lines.\n\nComments are counted by default because large comment-heavy files can still become hard to review. You may set `countCommentLines` to `false` in the config for a lighter check.\n\nGenerated, vendored, designer, minified, migration, lock, snapshot, and machine-produced files should normally be excluded by configuration.\n\n## Agent skill\n\nThe skill lives at:\n\n```text\nskills/loc-guard/SKILL.md\n```\n\nFor Claude Code, this can be installed as a project or personal skill.\n\nFor Codex, keep the policy in `AGENTS.md`, include the skill directory when your workflow uses skills, and keep `skills/loc-guard/agents/openai.yaml` with the skill for UI visibility.\n\n## Hook examples\n\nCodex example:\n\n```text\nhooks/codex/hooks.example.json\n```\n\nClaude example:\n\n```text\nhooks/claude/settings.example.json\n```\n\nThese are examples because exact hook configuration can vary by local setup and agent version.\n\n## GitHub Actions\n\nA workflow example is provided at:\n\n```text\nci/github/loc-guard.yml\n```\n\nCopy it to:\n\n```text\n.github/workflows/loc-guard.yml\n```\n\nThis repository also includes active CI at:\n\n```text\n.github/workflows/ci.yml\n```\n\nIt compiles the checker, runs the test suite, validates JSON examples, and runs LOC Guard against the repository.\n\n## Tests\n\nRun the publication test suite with:\n\n```bash\npython3 -m unittest discover -s tests\n```\n\n## Suggested agent instruction\n\nAdd this to `AGENTS.md` and/or `CLAUDE.md`:\n\n```markdown\n## LOC Guard\n\nUse the LOC Guard skill when creating or modifying source files.\n\nRun:\n\n```bash\npython3 .agent-tools/loc_guard.py . --config .agent-tools/loc-guard.config.json\n```\n\n400 counted LOC is a review trigger, not an automatic refactor command.\n\n600 counted LOC is a hard cap unless the user explicitly approves an exception.\n\nWhen a changed or new file warns, inspect cohesion, single responsibility, near-term growth, and whether splitting improves boundaries.\n\nReport either:\n\n- `warning accepted with justification: ...`\n- `split performed because: ...`\n```\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstef-k%2Fagent-loc-guard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstef-k%2Fagent-loc-guard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstef-k%2Fagent-loc-guard/lists"}