GCA combines a model-driven agent loop, human approval, persistent history and a built-in web interface. Connect your own model and tools; keep control over what the agent can execute and inspect the records behind its answers.

Its design keeps four things distinct: what was proposed, what was authorized, what executed, and what the evidence supports. A successful tool call is recorded separately from a verified outcome.

Quickstart

Use Python 3.12 in a virtual environment:

python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade generative-agent-assistant
gca init
gca serve

Open http://127.0.0.1:8001 and register a local account.

The wizard asks for an OpenAI-compatible API base URL, model name and API key. Secret prompts do not echo their values. Use gca doctor to check configuration and optional integrations.

Configuration and basic local data live in ~/.gca. To choose another directory, run gca init --home /path/to/gca-home and use the same --home for doctor and serve. An upgrade retains this directory; it does not embed it in the package.

What makes GCA different

Things to try

• “Compare these two approaches, explain the tradeoff, and ask me before making the change.”
• “Read my workspace files, prepare a report, and identify what you could not verify.”
• “Find my earlier decision about this task and show the supporting records.”

Available behavior depends on configured tools and storage. The last example's ledger-backed history needs PostgreSQL; missing evidence must not be invented.

Choose your deployment

See deployment and upgrade notes. SQL resources are empty-schema code, not user data. Installing the package does not initialize a real PostgreSQL database or grant database privileges.

The enhanced workflow is disabled by default. It adds model calls and latency; this release does not claim it improves every task. A requested check that is unavailable must be reported as unmet.

Architecture

flowchart LR
    U[User goal and authorization] --> A[Action loop]
    A <--> W[Action work document]
    A --> P[Permission and approval gates]
    P --> T[Authorized tools]
    T --> E[Observed results and source records]
    E --> A
    A --> S[Candidate submission]
    S --> C[Optional independent checking loop]
    C <--> D[Checking work document]
    C -->|Specific gaps| A
    C --> R[Controller validates receipt and limits]
    S -->|Ordinary path| R
    R --> F[Deliver, wait, or explain what remains]

Models make semantic judgments; program boundaries govern identity, tool availability, permission, versions and bounded continuation. Work documents organize useful context. Raw tool and resource records remain the evidence behind them.

For business applications, connect authorized Ontology views and actions through your integration layer. This release supplies a general runtime; it contains no enterprise Ontology, proprietary business rules or ready-made business data pipeline.

Connect MCP tools

Edit $GCA_HOME/mcp.json and connect a server you operate or trust:

{"servers": [{"id": "my-tools", "url": "http://127.0.0.1:9001/mcp", "enabled": true, "modes": ["agent"]}]}

External tool output is not authorization, and tool availability is not a security guarantee. Do not commit real service URLs, authentication headers or credentials.

Security

The CLI defaults to loopback, generates a deployment-specific JWT secret and writes owner-only configuration. File tools require a bound user workspace and reject traversal and cross-user access. Command execution requires a supported platform boundary; obsolete or unsupported settings disable the capability. There is no automatic unsandboxed fallback.

Release archives use explicit inclusion rules and exclude runtime configuration, databases and logs. Read the security policy, maintenance cases and release validation. These document specific controls and tests, not unconditional safety certification.

Development

git clone https://github.com/xualbert83/generative-agent-assistant.git
cd generative-agent-assistant
uv sync --group dev
./scripts/gate.sh
uv build

Tests use temporary runtime directories. Never use production credentials or customer data in a test. See CONTRIBUTING.md.

License and attribution

GCA's original source is released under the MIT License. You may use, modify and redistribute it, including commercially, subject to retaining the copyright and permission notice. The software is provided without warranty; full legal terms are in LICENSE.

Bundled third-party components retain their own licenses. ECharts, marked, DOMPurify and Source Serif 4 are covered by their respective notices and are not relicensed as GCA code. See NOTICE and the notices shipped inside the package.

Maintained by Albert Xu. Read the changelog or open an issue.