An evolving, learning SEO agent for your terminal. Audit websites against GEO (Generative Engine Optimization) standards, fix compliance issues, generate content that passes AI-citability checks, research keywords, and track improvements over time. Works with static HTML, Astro, Next.js, and WordPress.

Key capabilities:

• Full GEO audit with entity clarity, fact density, and schema scoring via innotekseoai.com MCP tools
• Three-phase remediation: surgical edits, new content creation, blog post generation — all in one /act run
• 25+ built-in commands: audit, fix, AEO analysis, competitor research, keyword research, content generation
• Session memory that persists across restarts — the agent remembers what it found and what you prefer
• Project learning that evolves over time — recurring issues tracked, skill files auto-updated
• Real-time streaming with Ink TUI, markdown rendering, tool detail display, and approval prompts

Prerequisites

Node.js 20+ required:

node --version  # Should show v20.x.x or higher

C++ build tools (one-time, for better-sqlite3):

• Mac: xcode-select --install
• Ubuntu/Debian: sudo apt install build-essential python3
• Windows (Admin PowerShell): npm install -g windows-build-tools

Installation

npm install -g innotekseo

Or from source:

git clone https://github.com/innotekseoai/innotekseo-console.git
cd innotekseo-console
npm install
npm run build
npm link

Verify: innotekseo --version

Getting API Keys

AI Provider (required)

Google Gemini (recommended — free tier):

1. Go to aistudio.google.com/apikey
2. Create API key (starts with AIza...)

| Provider | Free Tier | Key URL | |---|---|---| | Gemini | Yes | aistudio.google.com/apikey | | Anthropic | No | console.anthropic.com/settings/keys | | OpenAI | No | platform.openai.com/api-keys |

InnotekSEO MCP Tools (optional — enables GEO audit, competitor research)

1. Sign up at innotekseoai.com
2. Get API key from Dashboard > API Keys
3. Connect: /connect <your-key>

Quick Start

cd /path/to/your/website
innotekseo

First launch walks through setup (provider, API key, project detection). After setup:

> /scan          # Scan all pages
> /audit         # Full GEO audit with scores
> /act           # Apply recommended fixes
> /aeo           # AI-citability analysis
> /competitor    # Content gap analysis

CLI Options

innotekseo                             # Interactive mode
innotekseo --dir ~/project             # Specify project directory
innotekseo --provider anthropic        # Override AI provider
innotekseo --model gemini-2.5-pro      # Override model
innotekseo --prompt "/audit" --quiet   # Non-interactive mode
innotekseo --rekey                     # Re-enter API key

Commands

SEO & GEO Commands

| Command | What it does | |---|---| | /scan | Discover all pages, list SEO issues | | /audit | Full GEO audit via MCP — entity clarity, fact density, schema scores | | /aeo | Answer Engine Optimization analysis — AI-citability checks | | /fix | Auto-fix SEO issues across all pages | | /act | Execute remediation plan (three-phase: edits + content + blog posts) | | /schema | Generate JSON-LD structured data | | /meta | Generate optimized titles and descriptions | | /competitor | Analyze content gaps vs competitors | | /localize <city> | Rewrite content for a target city | | /newBlog <topic> | Write a GEO-compliant blog post | | /write <topic> | Generate any content (auto-injects audit context) |

Keyword Research Commands

| Command | What it does | |---|---| | /keywords <topic> | 50 keywords grouped by type + search intent | | /buyerkeys <product> | 30 high-converting buyer-intent keywords | | /programmatic <niche> | 10 keyword formulas + 50 scalable examples | | /gaps <competitor> | Keyword gaps and opportunities vs competitor | | /clusters <niche> | 10 pillar topics with 5 clusters each + linking plan | | /localkeys <business> | Local SEO keywords ("near me", service, long-tail) | | /trending <topic> | Emerging keywords, rising topics, cross-platform | | /questions <topic> | 30 question keywords for featured snippets |

Session & Settings Commands

| Command | What it does | |---|---| | /status | Show current config, tools, session context | | /model <name> | Switch LLM model (persists across sessions) | | /settings | Manage provider, model, mode, URL, keys | | /startup | Configure auto-actions on launch | | /remember <text> | Save a preference for this project | | /connect <key> | Connect to InnotekSEO MCP tools | | /plan <cmd> | Preview a command without executing | | /help | Show all available commands | | /compact | Summarize conversation, free context | | /reset | Clear conversation | | ! <cmd> | Run a shell command |

Agentic Workflows

Audit → Fix → Verify

/audit                          # MCP GEO audit → saves remediation plan
/act                            # Three-phase execution:
                                #   Phase 1: Edit existing pages (remediation worker)
                                #   Phase 2: Create new content sections (content worker)
                                #   Phase 3: Draft blog posts from recommendations
/audit                          # Re-audit to verify score improvement

Competitor → Content Generation

/competitor                     # MCP competitor research + counter-content
/act                            # Creates new pages from competitor gaps
                                # Counter-content converted to structured blog posts

AEO Analysis → Targeted Fixes

/aeo                            # Read-only AI-citability analysis
                                # Scores: structured answers, FAQ, schema, entity clarity
/fix                            # Apply recommended structural improvements
/write FAQ for cloud services   # Generate FAQ with matching schema

Natural Language Interaction

After any analysis command, use freeform chat:

> /audit
> what did you find?            # Agent answers from session memory
> fix the H1 on contact page    # Agent knows which H1 from audit
> write a case study about that # Agent uses competitor context

Memory & Learning

Session Memory (survives terminal restart)

• Audit findings, AEO scores, competitor gaps tracked per session
• Status bar shows: Audit: 8/10 · 3 pending · 2 edits applied
• Freeform chat references prior findings without re-running commands
• Saved to .innotekseo/session-memory.json, loaded on session resume

Project Memory (evolves over time)

• Audit score trends tracked across sessions
• Recurring issue patterns recorded with fix strategies
• Tool outcomes tracked (success/failure rates)
• Skill notes auto-appended to .innotekseo/INNOTEKSEO.md
• Stored in project.db — persists forever

User Preferences

/remember always use short H1 titles
/remember use FAQ schema on all service pages
/remember brand voice is professional and direct

Preferences saved to .innotekseo/preferences.md, loaded into agent context every session.

Persistent Settings

• /model gemini-2.5-pro — saved to project config, persists across sessions
• /settings provider anthropic — saved to global config
• /settings mode autopilot — saved to both global and project config
• /startup scan on — auto-run /scan on launch

Content Generation Quality

Content generation follows GEO compliance standards:

Entity Data Block (first paragraph of every page)

[Brand] (Company No. [number]), based at [registered address],
is a [industry] delivering [service]. [Verifiable metric].
Contact: [phone] or [email].

Quality Checklist

• H1 includes brand name: "Topic — Brand" pattern
• First paragraph: brand + founder + location + industry
• 3+ brand mentions in visible prose
• 5+ verifiable facts (10+ for service pages)
• Fact density under 80 words per fact
• H2 headings self-explanatory out of context
• Page-specific JSON-LD schema with @id references
• FAQ: both visible HTML AND FAQPage schema
• Testimonials under 40 words, keep quantified outcomes
• Image alt text includes brand + specific context
• No heading level skips (H1 → H2 → H3)
• Phone/email consistent across schema + HTML + llms.txt

Validator Catches

The built-in validator blocks writes that would break builds:

• Invalid JSON-LD syntax
• Frontmatter errors (duplicate fences, missing declarations)
• Template variable mismatches
• Escaped apostrophes, trailing backslashes
• Heading hierarchy violations
• Placeholder data patterns

Supported Websites

| Framework | Detection | Capabilities | |---|---|---| | Static HTML | .html files | Read/write HTML, meta tags, JSON-LD | | Astro | astro.config.* | Frontmatter, content collections, components | | Next.js | next.config.* | App Router + Pages Router metadata | | WordPress | wp-config.php | WP-CLI, REST API, SFTP, Yoast/RankMath |

Architecture

bin/cli.ts                  CLI entry point (commander)
src/
├── agent/
│   ├── runtime.ts           ReAct loop with streaming + repetition detection
│   ├── context.ts           Token budget management + conversation trimming
│   ├── content-worker.ts    GEO-compliant content generation agent
│   ├── remediation-worker.ts  Strict instruction executor
│   ├── site-identity.ts     Brand voice/style snapshot from key pages
│   ├── instruction-classifier.ts  Parse instructions into edit/content/blog
│   └── skill-evolution.ts   Auto-evolving skill files from audit outcomes
├── llm/
│   ├── provider.ts          Unified LLM interface
│   ├── gemini.ts            Google Gemini (real streaming)
│   ├── anthropic.ts         Anthropic Claude (real streaming)
│   └── openai.ts            OpenAI GPT (real streaming)
├── mcp/
│   ├── client.ts            SSE transport with origin-fix for innotekseoai.com
│   └── tools.ts             8 MCP tool definitions
├── commands/
│   ├── built-in/            17 built-in commands (audit, aeo, fix, keywords...)
│   ├── executor.ts          Simple/workflow/agentic command dispatch
│   └── loader.ts            YAML custom command loading
├── project/
│   ├── detector.ts          Framework auto-detection
│   ├── adapter.ts           ProjectAdapter interface
│   ├── astro-adapter.ts     Astro frontmatter + content collections
│   ├── nextjs-adapter.ts    Next.js App/Pages Router
│   ├── html-adapter.ts      Static HTML parsing
│   └── wordpress/           WP-CLI, REST API, SFTP, SEO plugins
├── tools/
│   ├── fs.ts                File tools with fuzzy matching + content validation
│   ├── git.ts               Git operations
│   ├── scan.ts              Project page discovery
│   └── registry.ts          Tool registry with execution timing
├── store/
│   ├── db.ts                SQLite (global + project databases)
│   ├── schema.ts            Drizzle ORM table definitions
│   ├── config-store.ts      Project + LLM config CRUD
│   ├── history-store.ts     Conversation + audit history
│   └── project-memory.ts    Persistent learning (audit trends, issue patterns)
├── security/
│   ├── keychain.ts          AES-256-GCM encrypted API key storage
│   └── sandbox.ts           Filesystem path validation
├── terminal/
│   ├── index.ts             Launch orchestrator
│   ├── session.ts           Session management + agent lifecycle
│   ├── session-memory.ts    Working memory (findings, actions, suggestions)
│   ├── stream-adapter.ts    Debounced streaming callbacks
│   ├── approval-logic.ts    Tool approval (supervised/autopilot)
│   ├── ui/
│   │   ├── Chat.tsx         Main chat orchestrator
│   │   ├── ChatHistory.tsx  Static + dynamic message rendering
│   │   ├── MarkdownText.tsx Markdown → ANSI terminal rendering
│   │   ├── ToolDetail.tsx   Rich tool result display (diffs, previews)
│   │   ├── DiffView.tsx     Inline red/green diff display
│   │   ├── ApprovalPrompt.tsx  Context-aware approval with diffs
│   │   ├── InputField.tsx   Multiline input (Ctrl+J)
│   │   ├── StatusBar.tsx    Provider + model + session context
│   │   └── commands/
│   │       ├── slash-handlers.ts   All /command routing + MCP orchestration
│   │       ├── shell-handler.ts    ! prefix shell execution
│   │       └── helpers.ts          Instruction templates + suggestions
│   └── config/              Global + project config management
├── rules/
│   ├── constants.ts         SEO thresholds, agent limits
│   ├── validators.ts        Content validation (pre-write checks)
│   └── framework-rules.ts   Framework-specific rules
└── content/
    └── fact-extractor.ts    Regex-based fact extraction from pages

Key Design Decisions

• Custom ReAct agent loop — no LangChain/Vercel AI SDK. Direct control over streaming, tool dispatch, and context management.
• Three agent types — main agent (full tools), content worker (creative, temp 0.7), remediation worker (strict executor, temp 0.2)
• readOnly commands — analysis commands (audit, AEO, keywords) physically cannot call edit_file
• Fresh agents per command — each /fix, /schema, /meta gets a clean agent with system context but no accumulated conversation pollution
• Session memory + project memory — two-layer persistence. Session memory for immediate context, project memory for long-term learning.
• Validate before write — content validation runs BEFORE fs.writeFileSync, not after. Invalid content is rejected, not written.
• MCP auto-reconnect — SSE connections drop; tool handlers transparently reconnect on next call.

Development

npm install            # Install dependencies
npm run build          # Build with tsup
npm run dev            # Watch mode
npm run test           # Run all 426 tests
npm run test:watch     # Watch tests
npm run typecheck      # TypeScript check

Project Stats

• 105 source files | 49 test files | 426 tests
• 25+ built-in commands | 3 agent types | 8 MCP tools
• 5 learning DB tables | 3 framework adapters | 3 LLM providers

License

MIT — see LICENSE for details.