Project Info
FirstPass
AI-powered pre-submission permit-readiness assistant for architecture and building projects.
Upload a plan set (PDF or DWG), and FirstPass runs a multi-agent pipeline: it resolves the jurisdiction, researches the governing building codes, reads your plans, runs compliance checks, audits the findings, and produces a cited permit-readiness report with a score, flagged issues, and a missing-documents checklist.
FirstPass is a pre-submission compliance assistant, not official permit approval. Findings indicate likely issues for early correction and require confirmation by a licensed professional and the governing jurisdiction.
Built for the UC Berkeley AI Hackathon 2026 by Kiro Moussa, Varun Sanjeev, David Pelazini, and Krishiv Bhatia.
Devpost submission →
Demo video: youtu.be/xaxAYptLR-M
The problem
Most permit submissions don't pass on the first try. Rules live across municipal portals, state amendments, and PDF code books — technically public, but hard to navigate without a compliance team. Architecture firms lose weeks (and clients) to avoidable rejections.
FirstPass is the first pass a plan set gets before a city plan reviewer sees it: catch likely violations early, with official citations and retrieval dates, in minutes instead of months.
How it works
Upload plans → Jurisdiction → Code research → Plan reading → Compliance → Review → Report
- Jurisdiction — Resolve the city and responsible agencies from the project address.
- Research — Agents browse official municipal and state code sources (live via Browserbase, or cached corpus in Redis).
- Read — Claude vision extracts structured facts from the plan set (setbacks, height, unit size, sheet inventory).
- Comply — Deterministic checks compare extracted facts against jurisdiction rules.
- Review — An auditor agent challenges findings; Arize evals catch misapplied rules and hallucinations.
- Report — A scored, cited readiness report with PASS / FAIL / WARNING / NEEDS REVIEW per check.
The live Run screen shows the pipeline step-by-step: agent activity, tools in use, violations as they stream, and retrieved code sections. When checks finish, open the dashboard to inspect findings on the plan viewer and download the full report.
Results
Sample output from a Los Angeles residential project. FirstPass reads the plan set in the Autodesk viewer, extracts setbacks and height from the sheets, runs deterministic compliance against the local code corpus, and surfaces a permit-readiness score with cited findings — violations flagged, items needing review, and passes called out per check.
Sponsor tools (hackathon stack)
FirstPass is built around the hackathon sponsor integrations. Each tool has a visible role in the product — not just a logo in the footer.
| Tool | Role in FirstPass |
|---|---|
| Band | Multi-agent orchestration. Python agents (CEO, researchers, visual analysis, compare codes, permit agent) collaborate in a real Band room. The dashboard shows live agent activity and @mention-driven handoffs. |
| Browserbase | Headless browser for live navigation of official city permitting sites and code portals. Retrieves source URLs, excerpts, and retrieval timestamps for every citation. |
| Redis | Shared brain: project state, multi-agent blackboard (project:{id}:blackboard), code corpus, and RedisVL hybrid search (vector + BM25) for token-efficient code retrieval. |
| Arize | Tracing and evaluation. Runs citation, authority, applicability, and hallucination evals on findings; powers the "caught mistake" demo moment when a misapplied rule is corrected live. |
| Claude (Anthropic) | Plan reading (vision), agent reasoning, rule interpretation, and report writing. Default model: claude-haiku-4-5-20251001. |
| Autodesk Platform Services | DWG upload, Model Derivative translation, and in-browser plan sheet viewer for .dwg uploads. |
| Vercel | Next.js hosting, SSE streaming for live run updates, serverless API routes. |
Every integration degrades gracefully — the app runs and demos with zero API keys using cached demo data, in-memory Redis fallback, and prebuilt viewer assets. Add keys in .env.local to make each integration go live.
Agent team
Python Band agents (run locally alongside the web app):
| Agent | What it does |
|---|---|
| CEO Boss | Delegates the run and kicks off the workflow |
| Project & Property Manager | Writes the project brief from address + plan metadata |
| Municipal Code Researcher | Scrapes city building codes via Browserbase |
| State Code Researcher | Scrapes California state amendments |
| Code Synthesizer | Merges municipal + state findings into one conclusion |
| Visual Analysis | Reads the plan set with Claude vision |
| Compare Codes | Flags plan-vs-code violations |
| Solutions Agent | Suggests design fixes for flagged issues |
| Permit Agent | Researches the city's permit portal and submittal checklist |
See PLAN.md for the full product spec and docs/REDIS_PLAN.md for the Redis blackboard + RAG architecture.
Tech stack
| Layer | Technology |
|---|---|
| Frontend | Next.js 15 (App Router), React 19, Tailwind CSS |
| Backend | Next.js API routes, Server-Sent Events for live pipeline streaming |
| Agents | Python 3.11+, Band SDK, Playwright |
| Plan reading | Claude vision (@anthropic-ai/sdk), MuPDF for PDF rendering |
| Storage | Redis (ioredis) with in-memory fallback |
| Code retrieval | RedisVL hybrid search + lexical fallback |
| Observability | OpenTelemetry → Arize |
| Deploy | Vercel |
Quick start
# Web app
npm install
cp .env.example .env.local # optional — app demos without keys
npm run dev # http://localhost:3000
# Python Band agents (optional — for live multi-agent runs)
cp firstpass.config.yaml.example firstpass.config.yaml
uv sync
./scripts/run_agents.sh
Try the demo: open the app, enter a project address, upload a plan set (PDF or DWG — Los_Angeles_(1).dwg works well), and click Run FirstPass. The demo pipeline runs real plan reading and compliance against the cached Los Angeles code corpus.
Running Band agents
Start the research agents in parallel:
./scripts/run_agents.sh
# or individually:
uv run firstpass-municipal
uv run firstpass-state
uv run firstpass-synthesizer
uv run firstpass-compare
Kick off a run in Band (address only):
@varbtw/ceo-boss @varbtw/project-property-intake
1216 E 92nd St, Los Angeles, CA 90002
Or from the CLI:
uv run firstpass-kickoff --address "1216 E 92nd St, Los Angeles, CA 90002"
Scrape codes without Band (no Claude API cost):
uv run firstpass-local --address "1109 Evelyn Ave, Albany, CA 94706"
Output lands in output/municipal_codes.txt, output/state_codes.txt, and output/final_summary.txt.
Environment variables
Copy .env.example → .env.local. Key integrations:
ANTHROPIC_API_KEY= # Claude — plan reading, agents, reports
BROWSERBASE_API_KEY= # Live code portal navigation
BROWSERBASE_PROJECT_ID=
REDIS_URL= # Shared state + code corpus (Upstash works on Vercel)
ARIZE_API_KEY= # Tracing + finding evals
ARIZE_SPACE_ID=
BAND_API_KEY= # Real Band collaboration rooms
APS_CLIENT_ID= # DWG → viewer translation
APS_CLIENT_SECRET=
Full reference: .env.example. Agent registration and Band handles: BAND_AGENTS.md (local copy, gitignored).
Deploy
vercel --prod
Add the env vars from .env.example in your Vercel project settings. Redis URL should use rediss:// for Upstash/Redis Cloud.
Project structure
src/
app/ Next.js pages + API routes (run, plans, projects, ingest)
components/ Dashboard, RunProgress, PlanSheetViewer, AgentFeed, …
lib/ Pipeline, compliance engine, Redis store, integrations
firstpass/ Python Band agents + Browserbase tools
data/demo/ Prebuilt Los Angeles plan set + viewer cache for zero-config demos
scripts/ Agent runners, code indexing, demo viewer builder
docs/ Redis plan, chunking strategy
Disclaimer
FirstPass is a pre-submission compliance assistant, not an official permit review. Findings indicate likely issues for early correction and require confirmation by a licensed professional and the governing jurisdiction. FirstPass does not approve, certify, or guarantee permit approval.
License
Private — UC Berkeley AI Hackathon 2026 submission.
Analysis
View
Metric
- 19
- 16
- 8
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- CSSIn code
- Next.jsIn code
- OpenAIIn code
- PythonIn code
- ReactIn code
- RedisIn code
- Tailwind CSSIn code
- TypeScriptIn code
8 of 8 appear in the indexed code.
AI coding agents
- Claude CodeCommits
- CursorCommits
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
39 MB
Source files
175
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
kiromoussa/FirstPass
259 files · 133.2 MB · @ 093e479
Structure
Interface
31 files · 12%Screens, components and styles rendered to the user.
API & routing
18 files · 7%Request entry points: routes, handlers and controllers.
Application logic
97 files · 37%Domain rules, services and shared utilities.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- Markdown98%
- TypeScript1%
- Python1%
- CSS0%
- Shell0%
- YAML0%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
package.json
npm · 22- @clerk/nextjs
- @opentelemetry/api
- @opentelemetry/exporter-trace-otlp-proto
- @opentelemetry/resources
- @opentelemetry/sdk-trace-node
- @opentelemetry/semantic-conventions
- @vercel/blob
- fflate
- ioredis
- mupdf
- next
- playwright-core
- react
- react-dom
- +8 more
pyproject.toml
pypi · 12- band-sdk
- beautifulsoup4
- browserbase
- httpx
- openai
- playwright
- pydantic
- pypdf
- pyyaml
- redis
- +2 more
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
Feature verification
Arize tracing and evaluation (citation, authority, applicability, hallucination evals)Verified
Arize runs citation, authority, applicability, and hallucination evals on findings; powers a 'caught mistake' demo moment when a misapplied rule is corrected live
Claimed on readmehigh confidencesrc/lib/integrations/arize.ts:22— evaluateFinding computes applicability, authority (and presumably citation/hallucination) eval dimensions with scores/pass thresholdssrc/lib/pipeline.ts:591— Reviewer stage emits a 'disagreement' message and re-runs compliance when an eval fails, implementing the self-correcting 'caught its own mistake' behaviorsrc/lib/integrations/otel.ts:12— OTLP exporter sends spans to otlp.arize.com when ARIZE_API_KEY/SPACE_ID are set
Autodesk Platform Services DWG upload, translation, and in-browser viewerVerified
DWG upload, Model Derivative translation, and in-browser plan sheet viewer for .dwg uploads
Claimed on readmehigh confidencesrc/lib/integrations/aps.ts:9— APS_LIVE gated on client id/secret; implements 2-legged token, OSS bucket upload, Model Derivative job flowsrc/components/DwgViewer.tsx:12— DwgViewer renders ApsSheetViewer with fallback to PlanSheetViewer (plotted PNG) when APS translation is unavailable
Autonomous jurisdiction researcher ingesting official code sites into Redis corpusVerified
Agents browse official municipal and state code sources (live via Browserbase, or cached corpus in Redis) and derive rules
Claimed on readmemedium confidencescripts/ingest_band_output.py— Script ingests Band agent research output into the code corpus, matching the 'ingest' step of the claimed research pipelinescripts/chunk_codes.py— Script chunks scraped code text into the corpus format consumed by compliance/retrievalsrc/lib/city-research.ts— TS module coordinating city/jurisdiction research on the app side
Band multi-agent orchestration with live room and agent handoffsVerified
Python agents (CEO, researchers, visual analysis, compare codes, permit agent) collaborate in a real Band room; dashboard shows live agent activity and @mention-driven handoffs
Claimed on readmehigh confidencesrc/lib/integrations/band.ts:13— BAND_LIVE flag gated on BAND_API_KEY, phased chat structure (Intake & Code, Design Review, Closeout) with @mention message constructionsrc/firstpass/band_client.py— Referenced by redis_store.py as the Python side of Band integration for agent collaborationsrc/components/AgentFeed.tsx:63— UI component renders agent messages with sponsor badges, showing live agent activity
Browserbase live navigation of official code/permitting sites with cited retrieval datesVerified
Headless browser retrieves source URLs, excerpts, and retrieval timestamps for every citation from official city permitting sites and code portals
Claimed on readmehigh confidencesrc/lib/integrations/browserbase.ts:8— BROWSERBASE_LIVE flag gated on API key/project id; cityCachedSources builds Source objects with retrievedAt timestamps and authorityScore from official domainssrc/firstpass/browserbase_tool.py— Dedicated Python tool module for Browserbase scraping used by municipal/state research agents
Claude vision plan reading (extracts setbacks, height, unit size, sheet inventory)Verified
Claude vision extracts structured facts from the plan set (setbacks, height, unit size, sheet inventory)
Claimed on readmehigh confidencesrc/lib/integrations/llm.ts:165— extractPlanFacts function takes base64 page images and performs structured extraction; extractPlanFactsFromSheetImages handles labeled sheet tiles with bbox localization
Code synthesizer merges municipal + state findingsVerified
Code Synthesizer merges municipal + state findings into one conclusion
Claimed on readmemedium confidencesrc/firstpass/agents/synthesizer.py— Dedicated synthesizer agent module presentsrc/firstpass/synthesis.py— Supporting synthesis logic module exists alongside the agent
Deterministic compliance engine (PASS/FAIL/WARNING/NEEDS REVIEW per check)Verified
Deterministic checks compare extracted facts against jurisdiction rules, producing a scored, cited readiness report with PASS/FAIL/WARNING/NEEDS REVIEW per check
Claimed on readmehigh confidencesrc/lib/compliance.ts:30— compareNumeric classifies findings into NEEDS_REVIEW/WARNING/PASS/FAIL based on measured value vs threshold, with a scoreFrom function aggregating statuses
Graceful degradation with zero API keys (cached demo data, in-memory Redis fallback)Verified
Every integration degrades gracefully; the app runs and demos with zero API keys using cached demo data, in-memory Redis fallback, and prebuilt viewer assets
Claimed on readmehigh confidencesrc/lib/integrations/browserbase.ts:1— Comment and code explicitly serve cached official-source set when Browserbase is not livesrc/lib/integrations/aps.ts:26— getToken returns null when APS is not configured rather than throwing, enabling graceful degradationdata/demo/los-angeles-1— Prebuilt demo plan set and viewer cache directory exists for zero-config demos, matching README's data/demo description
Jurisdiction resolution from project addressVerified
Resolve the city and responsible agencies from the project address
Claimed on readmehigh confidencesrc/firstpass/jurisdiction.py:21— CITY_REGISTRY maps cities to JurisdictionProfile with official domains, municode host, and municipal seed URLs, with resolve_from_address referenced elsewhere
Live Run screen with step-by-step pipeline streaming (SSE)Verified
The live Run screen shows the pipeline step-by-step: agent activity, tools in use, violations as they stream, and retrieved code sections
Claimed on readmehigh confidencesrc/app/api/run/[id]/route.ts— Route implements SSE streaming (grep matched ReadableStream/text/event-stream) for live run updatessrc/components/RunProgress.tsx— Dashboard component name matches the claimed live Run screen
Missing-documents checklistVerified
Produces a missing-documents checklist as part of the readiness report
Claimed on readmehigh confidencesrc/lib/pipeline.ts:537— deriveChecklist computes required documents from facts/docTypes and filters for missing required items, emitting a checklist findingsrc/firstpass/permit/checklists.py:11— PermitChecklist/ChecklistItem dataclasses define city-specific required submission items
Multi-agent pipeline orchestration (jurisdiction, research, plan reading, compliance, review, report)Verified
FirstPass runs a multi-agent pipeline that resolves jurisdiction, researches codes, reads plans, runs compliance checks, audits findings, and produces a report
Claimed on readmehigh confidencesrc/lib/pipeline.ts:570— Pipeline sets state.project.status through stages including 'review' and emits reviewer/checklist/compliance messages, matching the claimed stage sequencesrc/firstpass/agents— Directory contains distinct agent modules (ceo.py, municipal.py, state.py, compare.py, visual.py, solutions.py, permit.py, synthesizer.py) matching the claimed agent team
Municipal and state code researchers scraping via BrowserbaseVerified
Municipal Code Researcher scrapes city building codes via Browserbase; State Code Researcher scrapes California state amendments
Claimed on readmehigh confidencesrc/firstpass/agents/municipal.py— Dedicated municipal researcher agent modulesrc/firstpass/agents/state.py— Dedicated state researcher agent modulesrc/firstpass/browserbase_tool.py— Shared Browserbase scraping tool used by these research agents
Permit agent researches city's permit portal and submittal checklistVerified
Permit Agent researches the city's permit portal and submittal checklist
Claimed on readmehigh confidencesrc/firstpass/agents/permit.py— Dedicated permit research agent modulesrc/firstpass/permit_research_tool.py— Supporting tool module for permit portal researchsrc/firstpass/permit/checklists.py:11— Implements per-city submission checklist data used by the permit agent
Redis as shared blackboard and project/code-corpus state storeVerified
Redis functions as shared brain for project state, multi-agent blackboard (project:{id}:blackboard), and code corpus
Claimed on readmehigh confidencesrc/firstpass/redis_store.py:18— Documents and implements project:{id}:blackboard HASH and project:{id}:events PUBSUB keys shared between Python agents and the Next.js store
RedisVL hybrid search (vector + BM25) for code retrievalVerified
RedisVL hybrid search (vector + BM25) for token-efficient code retrieval
Claimed on readmehigh confidencescripts/index_codes_redisvl.py:1— Builds a RedisVL index combining BM25 full-text, vector field for semantic recall, and TAG filters for jurisdiction/applicabilityscripts/query_codes_redisvl.py:61— Implements VectorQuery-based KNN search against the firstpass:codes index
Solutions agent suggests design fixes for flagged issuesVerified
Solutions Agent suggests design fixes for flagged issues
Claimed on readmehigh confidencesrc/firstpass/agents/solutions.py— Dedicated agent module for solutions/design fix suggestionssrc/lib/compliance.ts:72— suggestFix function computes exact remediation deltas for FAIL/WARNING findings
Vercel hosting with SSE streaming and serverless API routesVerified
Next.js hosting, SSE streaming for live run updates, serverless API routes on Vercel
Claimed on readmemedium confidencesrc/app/api/run/[id]/route.ts— SSE route implementation found via grep for ReadableStream/text/event-streampackage.json— Next.js project structure with API routes under src/app/api consistent with Vercel serverless deployment (deploy step itself is external and not verifiable from code alone)
DWG/PDF plan upload supporting Los_Angeles_(1).dwg demo fileCode-supported
Upload a plan set (PDF or DWG); Los_Angeles_(1).dwg works well for the demo
Claimed on readmemedium confidencesrc/app/api/plans/upload— Dedicated upload API route exists for plan setssrc/app/api/dwg/stage— Dedicated staging route exists for DWG files, consistent with DWG upload support, though the specific demo filename in data/demo was not directly inspected
An AI agent derived these features from the project’s Devpost page and readme, then searched the code for each one. Verified features are backed by cited code; claimed-only features had no supporting code, which is not by itself proof a feature is missing.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.