From 44c1e777098d5f783155c4874d49917bddae55df Mon Sep 17 00:00:00 2001 From: Srujan Amaragatti Date: Sat, 9 May 2026 20:05:46 +0530 Subject: [PATCH 1/6] feat: add landing page for codectx.granth.tech --- docs/astro.config.mjs | 9 +- docs/src/pages/index.astro | 1037 ++++++++++++++++++++++++++++++++++++ 2 files changed, 1039 insertions(+), 7 deletions(-) create mode 100644 docs/src/pages/index.astro diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index b4fe697..181a9d5 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -1,14 +1,9 @@ import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; -// Local dev defaults to root path; production keeps GitHub Pages subpath. -const isProduction = process.env.NODE_ENV === 'production'; -const docsBase = process.env.DOCS_BASE ?? '/'; - // https://astro.build/config export default defineConfig({ - site: 'https://hey-granth.github.io', - base: docsBase, + site: 'https://codectx.granth.tech', integrations: [ starlight({ title: 'codectx', @@ -71,4 +66,4 @@ export default defineConfig({ ], }), ], -}); +}); \ No newline at end of file diff --git a/docs/src/pages/index.astro b/docs/src/pages/index.astro new file mode 100644 index 0000000..963cd8d --- /dev/null +++ b/docs/src/pages/index.astro @@ -0,0 +1,1037 @@ +--- +// codectx landing page — codectx.granth.tech +// Single page, dark terminal aesthetic, animated hero terminal demo +--- + + + + + + + codectx — Codebase context compiler for AI agents + + + + + + + + + + + + + + + + + +
+

v0.3.0 · MIT License · Python 3.10+

+ +

+ Feed LLMs signal,
not noise. +

+ +

+ codectx compiles your repository into a structured context file for AI agents — + ranking files by dependency graph centrality, compressing to a token budget, + and emitting a document an agent can reason from immediately. +

+ +
+
+ $ + pip install codectx + +
+

or: uv add codectx · pipx install codectx

+
+
+ + +
+ +
+ + +
+
+
+ 76% + avg token reduction +
+
+ 9 + languages supported +
+
+ 120k + default token budget +
+
+ 0.3.0 + latest version +
+
+ + Total downloads from PyPI + + total PyPI downloads +
+
+
+ + +
+
+

The problem

+

+ When you dump a repository into an LLM context window, you get files in filesystem + order — alphabetical, arbitrary, disconnected. The model sees tests before + the modules they test, utility helpers before the architecture they support, + config files before the code that reads them. +

+

+ Naive context dumps waste the most valuable positions in the context window on + noise. Most files in any codebase are boilerplate, test fixtures, and + auto-generated code — none of which helps an agent understand the system. +

+

+ Arbitrarily truncating at a token limit doesn't help either. You might cut off + the core module and keep a lockfile. +

+
+ +
+

The fix

+

+ codectx builds a dependency graph of your repository, then scores + every file by its fan-in centrality — how many other files import it. Files that + everything depends on rank highest. +

+

+ Git commit frequency, distance from entry points, and (optionally) semantic + similarity to your query combine into a composite score. The top 15% of files get + full AST-derived structured summaries. The next 30% get function + signatures. The rest get one-liners. +

+

+ The output is not a source dump. It is a compiled document an agent can navigate + from the first token — architecture first, then core modules, then periphery. +

+
+
+ + +
+

Before vs after

+
+ +
+
+ cat **/*.py | llm + naive +
+
+ 1# conftest.py — pytest fixtures
+ 2import pytest
+ 3from myapp.db import engine
+ 4
+ 5# setup.py — package config
+ 6from setuptools import setup
+ 7setup(name='myapp', ...)
+ 8
+ 9# __init__.py
+ 10pass
+ 11
+ 12# ... 40 more files in random order
+ 13# core/engine.py buried at line 4,847
+
+
≈ 224,000 tokens · exceeds 128k window · no structure
+
+ + +
+
+ CONTEXT.md + codectx +
+
+ ## ARCHITECTURE
+ Request processing engine. 3 subsystems.
+
+ ## ENTRY_POINTS
+ ### `cli.py` (tier 1, score 0.94)
+ Full source — 312 lines
+
+ ## CORE_MODULES
+ ### `core/engine.py`
+ Purpose: Main execution engine.
+ Depends on: core.models, cache
+ Functions: process(), shutdown()
+
+ ## DEPENDENCY_GRAPH · RANKED_FILES · PERIPHERY
+
+
≈ 28,000 tokens · 87% reduction · structured
+
+
+
+ + +
+

Benchmarks — real repos

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RepositoryNaive tokenscodectx tokensReduction
fastapi224k78k
64.9%
requests41k6k
84.7%
typer80k35k
55.4%
rich354k28k
92%
httpx63k6k
89.5%
+
+ + +
+

Pipeline

+
+
+
🚶
+
Walker
+
scan files, apply .gitignore + .ctxignore
+
+
+
🌳
+
Parser
+
extract imports & symbols via tree-sitter
+
+
+
🕸
+
Graph
+
build dependency graph with rustworkx
+
+
+
📊
+
Ranker
+
score by fan-in, git frequency, proximity
+
+
+
🗜
+
Compressor
+
assign tiers, enforce token budget
+
+
+
📄
+
Formatter
+
emit structured CONTEXT.md
+
+
+
+ + + + + + + + From d0796b9ac1654db7372fc5c07d144abe26e23e5d Mon Sep 17 00:00:00 2001 From: Srujan Amaragatti Date: Sat, 9 May 2026 20:15:52 +0530 Subject: [PATCH 2/6] fix: remove base prefix so landing page serves at root --- docs/astro.config.mjs | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 181a9d5..ca77219 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -1,7 +1,6 @@ import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; -// https://astro.build/config export default defineConfig({ site: 'https://codectx.granth.tech', integrations: [ From 846bb3e5f613a50f04f71e8780dabcaa4b1de921 Mon Sep 17 00:00:00 2001 From: Srujan Amaragatti Date: Sat, 9 May 2026 20:29:30 +0530 Subject: [PATCH 3/6] fix: move starlight index so landing page can own root route --- docs/src/content/docs/{index.mdx => introduction.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/src/content/docs/{index.mdx => introduction.mdx} (100%) diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/introduction.mdx similarity index 100% rename from docs/src/content/docs/index.mdx rename to docs/src/content/docs/introduction.mdx From 0937683e97d7b6dc34a781b6851ac43eb17c5070 Mon Sep 17 00:00:00 2001 From: Srujan Amaragatti Date: Sat, 9 May 2026 21:46:59 +0530 Subject: [PATCH 4/6] fix: add TypeScript types to fix build errors --- docs/src/pages/index.astro | 195 ++++++++++++++++++------------------- 1 file changed, 94 insertions(+), 101 deletions(-) diff --git a/docs/src/pages/index.astro b/docs/src/pages/index.astro index 963cd8d..a41b379 100644 --- a/docs/src/pages/index.astro +++ b/docs/src/pages/index.astro @@ -930,108 +930,101 @@ + break; + } + + const isCommand = i === 0; + await typeLine(text, cls, isCommand ? CHAR_DELAY : 0); + await sleep(LINE_PAUSE); + } + } + + runAnimation(); + + const copyBtn = document.getElementById('copy-btn') as HTMLButtonElement | null; + if (copyBtn) { + copyBtn.addEventListener('click', async () => { + try { + await navigator.clipboard.writeText('pip install codectx'); + copyBtn.textContent = 'copied!'; + copyBtn.classList.add('copied'); + setTimeout(() => { + copyBtn.textContent = 'copy'; + copyBtn.classList.remove('copied'); + }, 2000); + } catch { + copyBtn.textContent = 'copy'; + } + }); + } + From cbaad301989c10e20c33684a3e405231b1121646 Mon Sep 17 00:00:00 2001 From: Srujan Amaragatti Date: Sat, 9 May 2026 22:01:33 +0530 Subject: [PATCH 5/6] fix: add netlify.toml to point to docs build output --- netlify.toml | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 netlify.toml diff --git a/netlify.toml b/netlify.toml new file mode 100644 index 0000000..11f4241 --- /dev/null +++ b/netlify.toml @@ -0,0 +1,4 @@ +[build] + base = "docs" + command = "npm install --legacy-peer-deps && npm run build" + publish = "docs/dist" \ No newline at end of file From 65c37623a92572a409561b068996e78e41a88df3 Mon Sep 17 00:00:00 2001 From: Srujan Amaragatti Date: Sat, 9 May 2026 22:08:45 +0530 Subject: [PATCH 6/6] fix: correct netlify publish directory path --- netlify.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netlify.toml b/netlify.toml index 11f4241..2761d06 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1,4 +1,4 @@ [build] base = "docs" command = "npm install --legacy-peer-deps && npm run build" - publish = "docs/dist" \ No newline at end of file + publish = "dist" \ No newline at end of file