edwin-hao-ai/setup

Setup Awareness Memory: check local daemon status, optionally authenticate via browser, select a memory, and write credentials to settings.json.

Cloud API base URL: https://awareness.market/api/v1 Local daemon URL: http://localhost:37800

Step 1 — Check local daemon

First check if the local Awareness daemon is running:

curl -sf http://localhost:37800/healthz 2>/dev/null && echo "DAEMON:RUNNING" || echo "DAEMON:NOT_RUNNING"

If daemon is running (DAEMON:RUNNING):

Get daemon status:

curl -sf http://localhost:37800/api/v1/status 2>/dev/null || echo "{}"

Tell the user:

Awareness local daemon is running!

Status: [show memory_id, mode, etc. from status response]
MCP URL: http://localhost:37800/mcp

Your local memory is ready to use.

Then ask: "Want to connect to Awareness Cloud for sync and sharing? (yes/no)"

• If no → jump to Step 5 (write local-only settings) and finish.
• If yes → continue to Step 2 (cloud auth).

If daemon is NOT running:

Check if user has existing cloud credentials (same logic as before):

1a. Check environment variables (from settings.json)

Read the current environment variables AWARENESS_API_KEY and AWARENESS_MEMORY_ID. If both exist AND AWARENESS_API_KEY starts with aw_ AND is NOT the placeholder aw_your-api-key-here, and AWARENESS_MEMORY_ID is NOT your-memory-id-here:

• Tell the user cloud credentials are already configured.
• Ask: "Do you want to re-configure? (yes/no)"
• If no → stop here. Suggest running /awareness-memory:session-start instead.
• If yes → continue to Step 2.

1b. Check ~/.awareness/credentials.json (left by npx @awareness-sdk/setup)

Run:

cat ~/.awareness/credentials.json 2>/dev/null

If the file exists and contains a valid api_key (starts with aw_):

• Tell the user: "Found existing Awareness credentials (from a previous setup). Reusing them."
• Extract the api_key and api_base values.
• Skip Step 2 and Step 3 — jump directly to Step 4 (Memory selection) using this api_key.

If no credentials found at all:

• Tell the user:

  Awareness Memory is not configured. You have two options:
  
  1. Start local daemon: npx @awareness-sdk/local start
     (Run this in a separate terminal, then re-run /awareness-memory:setup)
  
  2. Connect to cloud: Continue with browser authentication below
  
  Which option? (local/cloud) [cloud]:
  

• If "local" → tell user to run npx @awareness-sdk/local start in another terminal and re-run setup. Stop here.
• If "cloud" or empty → proceed to Step 2.

---

Step 2 — Device Code Auth (browser login)

Run the entire auth flow in a single Bash command. This is critical — do NOT poll in a loop with separate Bash calls.

Run this exact script (substituting nothing — it is self-contained):

python3 -c "
import os, urllib.request, json, subprocess, sys, time, platform

API = 'https://awareness.market/api/v1'

# --- headless detection (F-035) ---
# On SSH / Docker / Codespaces / no-TTY hosts we must not try to open
# a browser — the user is reading this via the Claude CLI on a remote
# host and needs to click the URL on a different device.
def is_headless():
    flag = os.environ.get('AWARENESS_HEADLESS', '').lower()
    if flag in ('1','true','yes','on'): return True
    if flag in ('0','false','no','off'): return False
    if any(os.environ.get(k) for k in ('SSH_CONNECTION','SSH_CLIENT','SSH_TTY')): return True
    if os.environ.get('CODESPACES','').lower() == 'true': return True
    if os.environ.get('GITPOD_WORKSPACE_ID'): return True
    if os.environ.get('CLOUD_SHELL','').lower() == 'true': return True
    if platform.system() == 'Linux' and not os.environ.get('DISPLAY') and not os.environ.get('WAYLAND_DISPLAY'): return True
    if not sys.stdout.isatty(): return True
    return False

HEADLESS = is_headless()

# --- init ---
req = urllib.request.Request(API + '/auth/device/init', data=b'{}',
      headers={'Content-Type':'application/json'}, method='POST')
try:
    resp = json.load(urllib.request.urlopen(req, timeout=15))
except Exception as e:
    print('ERROR:NETWORK:' + str(e)); sys.exit(1)

dc   = resp['device_code']
uc   = resp['user_code']
intv = resp.get('interval', 5)
ttl  = resp.get('expires_in', 900)

print('USER_CODE:' + uc)
print('HEADLESS:' + ('1' if HEADLESS else '0'))
print('TTL:' + str(ttl))
sys.stdout.flush()

# --- open browser (skip on headless) ---
url = 'https://awareness.market/cli-auth?code=' + uc
if HEADLESS:
    print('BROWSER:SKIPPED:' + url)
else:
    try:
        if platform.system() == 'Darwin':
            subprocess.run(['open', url], check=True, capture_output=True)
        elif platform.system() == 'Windows':
            subprocess.run(['start', '', url], shell=True, check=True, capture_output=True)
        else:
            subprocess.run(['xdg-open', url], check=True, capture_output=True)
        print('BROWSER:OPENED')
    except Exception:
        print('BROWSER:FAILED:' + url)
sys.stdout.flush()

# --- poll (up to ~14 min, aligned with backend TTL 900s) ---
max_polls = max(40, ttl // max(intv,1))
for i in range(1, max_polls + 1):
    time.sleep(intv)
    try:
        preq = urllib.request.Request(API + '/auth/device/poll',
               data=json.dumps({'device_code': dc}).encode(),
               headers={'Content-Type':'application/json'}, method='POST')
        pr = json.load(urllib.request.urlopen(preq, timeout=15))
    except Exception:
        if i % 4 == 0: print('POLL_ERROR:' + str(i))
        continue
    st = pr.get('status','')
    if st == 'approved':
        print('APPROVED:' + pr['api_key'])
        sys.exit(0)
    elif st == 'expired':
        print('EXPIRED'); sys.exit(1)
    if i % 4 == 0:
        print('WAITING:' + str(i) + '/' + str(max_polls))
    sys.stdout.flush()

print('TIMEOUT'); sys.exit(1)
"

Timeout for this Bash call: 840000 ms (14 minutes, aligned with F-035 backend TTL=900s).

Parse the output

The script prints structured lines. Parse them:

| Output prefix | Meaning | Action | |---------------|---------|--------| | USER_CODE:{code} | The human-readable auth code | Show to user (see message below) | | HEADLESS:0 or HEADLESS:1 | Whether host is headless (SSH/Docker/no-TTY) | Tailor instructions: on headless host, tell user to open URL on a second device | | TTL:{seconds} | Backend code lifetime (default 900 = 15 min) | Use in expiry message | | BROWSER:OPENED | Browser opened successfully | No action needed | | BROWSER:SKIPPED:{url} | Headless host — no browser attempt | Tell user to open the URL on any device with a browser | | BROWSER:FAILED:{url} | Could not open browser | Tell user to open the URL manually | | WAITING:{n}/{max} | Still polling | Silently continue waiting | | POLL_ERROR:{n} | Network blip during poll | Ignore unless many in a row | | APPROVED:{api_key} | Success! | Extract the api_key, proceed to Step 3 | | EXPIRED | Device code expired (15 min backend TTL) | Tell user to run /awareness-memory:setup again | | TIMEOUT | All polls exhausted, still pending | Ask user: keep waiting / start over / cancel | | ERROR:NETWORK:{msg} | Cannot reach server at all | Tell user to check network connection |

Show this message to the user IMMEDIATELY after launching the script

As soon as you see the USER_CODE: line in the output, tell the user:

Your authorization code is: {user_code}

A browser window should open. Please:
1. Sign in (or create an account) in the browser
2. Confirm the code matches: {user_code}
3. Click "Authorize CLI"

Waiting for authorization...

If you see BROWSER:FAILED:{url}, also add:

Could not open browser automatically. Please open this URL:
{url}

Handle TIMEOUT (user still hasn't authorized after ~200 seconds)

Ask the user:

• "Keep waiting" → run the same script again (new device code, fresh 200s window)
• "Cancel" → stop setup

Save credentials to ~/.awareness/ (for future reuse by npx @awareness-sdk/setup)

After getting the api_key:

mkdir -p ~/.awareness && printf '{"api_key":"%s","api_base":"https://awareness.market/api/v1"}\n' '{api_key}' > ~/.awareness/credentials.json && chmod 600 ~/.awareness/credentials.json

---

Step 3 — Verify API Key

Verify the obtained API key works. Run:

curl -s -w "\nHTTP_STATUS:%{http_code}" https://awareness.market/api/v1/memories -H "Authorization: Bearer {api_key}"

Parse the output:

• Look at the HTTP_STATUS: line at the end.
• HTTP 200 → key is valid. The JSON body before it is the memory list — save it for Step 4 (no need to fetch again).
• HTTP 401/403 → tell user: "API key appears invalid. Run /awareness-memory:setup again."
• Network error → warn but continue (might be transient).

---

Step 4 — Memory selection

4a. Parse memory list

Use the JSON response from Step 3 (already fetched). Parse it as a JSON array. Each memory object has at least id and name.

If Step 3 was skipped (reusing credentials from 1b), fetch the list now:

curl -s https://awareness.market/api/v1/memories -H "Authorization: Bearer {api_key}"

4b. Present choices

If user has 0 memories:

• Tell user: "You don't have any memories yet. Let's create one!"
• Jump to Step 4c.

If user has 1+ memories:

• Display a numbered list:

  Your memories:
    1. {name_1}
    2. {name_2}
    ...
    N+1. Create new memory
  
  Select a memory (1-{N+1}) [1]:
  

• Wait for user input.

Handle user's choice:

• Valid number 1-N → use that memory's id and name
• Number N+1 → jump to Step 4c
• Empty/blank → default to 1 (first memory)
• Invalid input → tell user valid range, ask again (max 3 retries, then default to 1)

4c. Create new memory (if selected)

Ask the user: "Describe what this memory is for (e.g. 'My startup project backend development'):"

If user gives empty input, use: "General-purpose memory for development workflow".

Create via wizard — run as a single Bash command:

python3 -c "
import urllib.request, json, sys

API  = 'https://awareness.market/api/v1'
KEY  = '{api_key}'
DESC = '''USER_DESCRIPTION_HERE'''

headers = {'Authorization': 'Bearer ' + KEY, 'Content-Type': 'application/json'}

# Step 1: wizard
wiz_body = json.dumps({'owner_id':'','locale':'en','messages':[{'role':'user','content': DESC}],'draft':{}}).encode()
wiz_req  = urllib.request.Request(API + '/wizard/memory_designer', data=wiz_body, headers=headers, method='POST')
try:
    wiz_resp = json.load(urllib.request.urlopen(wiz_req, timeout=30))
except Exception as e:
    print('ERROR:WIZARD:' + str(e)); sys.exit(1)

payload = wiz_resp.get('plan',{}).get('create_payload')
if not payload:
    print('ERROR:NO_PAYLOAD'); sys.exit(1)

# Step 2: create memory
create_req = urllib.request.Request(API + '/memories', data=json.dumps(payload).encode(), headers=headers, method='POST')
try:
    mem = json.load(urllib.request.urlopen(create_req, timeout=15))
except Exception as e:
    print('ERROR:CREATE:' + str(e)); sys.exit(1)

print('CREATED:' + mem['id'] + ':' + mem.get('name','New Memory'))
"

Replace USER_DESCRIPTION_HERE with the user's description (escape any single quotes by replacing ' with '\'').

Parse output:

• CREATED:{id}:{name} → success, use these values
• ERROR:WIZARD:... or ERROR:CREATE:... → tell user: "Could not create memory automatically. Create one at https://awareness.market/dashboard, then run /awareness-memory:setup again."

---

Step 5 — Write settings.json

5a. Find the settings.json file

The skill variable ${CLAUDE_SKILL_DIR} points to this skill's directory (skills/setup/). The plugin's settings.json is two levels up:

SETTINGS_PATH="${CLAUDE_SKILL_DIR}/../../settings.json"

Verify it exists:

[ -f "${CLAUDE_SKILL_DIR}/../../settings.json" ] && echo "SETTINGS_PATH:${CLAUDE_SKILL_DIR}/../../settings.json" || echo "SETTINGS_PATH:NOT_FOUND"

• If SETTINGS_PATH:NOT_FOUND → tell user: "Could not find plugin settings. Make sure the plugin is installed: /plugin marketplace add edwin-hao-ai/Awareness-SDK then /plugin install awareness-memory@awareness". Stop here.
• Otherwise → use the returned path.

5b. Write credentials

If local daemon mode (from Step 1, user chose not to connect cloud):

Use the Write tool (NOT Bash) to write the settings.json file. Content:

{
  "env": {
    "AWARENESS_MCP_URL": "http://localhost:37800/mcp",
    "AWARENESS_AGENT_ROLE": "builder_agent"
  }
}

If cloud mode (completed Steps 2-4):

Use the Write tool (NOT Bash) to write the settings.json file. Content:

{
  "env": {
    "AWARENESS_MCP_URL": "https://awareness.market/mcp",
    "AWARENESS_MEMORY_ID": "{memory_id}",
    "AWARENESS_API_KEY": "{api_key}",
    "AWARENESS_AGENT_ROLE": "builder_agent"
  }
}

---

Step 6 — Final summary

For local daemon mode:

Setup complete! (Local mode)

  MCP URL:   http://localhost:37800/mcp
  Mode:      Local-first

Your memory is stored locally. To sync with cloud later, run /awareness-memory:setup again.
To activate, restart Claude Code and then run:
  /awareness-memory:session-start

For cloud mode:

Setup complete! (Cloud mode)

  API Key:   {first 10 chars of api_key}...
  Memory:    {memory_name} ({memory_id})
  MCP URL:   https://awareness.market/mcp

To activate, restart Claude Code and then run:
  /awareness-memory:session-start

Clearly explain: a restart is needed because MCP connections are established at session start using the env vars from settings.json. The new credentials won't take effect until the next session.

---

Error handling summary

| Scenario | Action | |----------|--------| | Local daemon running | Show status, offer cloud connection | | Local daemon not running, no credentials | Offer local start or cloud auth | | Network unreachable (init fails) | Stop with clear message, suggest checking connection | | Browser won't open | Show manual URL from BROWSER:FAILED output | | User never authorizes (TIMEOUT) | Ask: keep waiting (re-run script) or cancel | | Device code expired (EXPIRED) | Tell user to re-run /awareness-memory:setup | | API key invalid (401 on verify) | Tell user to re-run setup | | No memories + wizard fails | Direct user to web dashboard | | settings.json not found | Tell user to install plugin first | | User gives invalid memory choice | Re-ask up to 3 times, then default to first |

Rules

• Run the auth polling as a single Bash call using the Python script — NEVER poll with separate Bash calls in a loop
• All JSON parsing must use python3 -c for consistency (do NOT use jq or other tools)
• Never show the raw device_code to the user — only show user_code
• Never dump raw JSON responses — always summarize in plain language
• Always mask API keys in output (show only first 10 characters + "...")
• If $ARGUMENTS contains "force" or "--force", skip the "already configured" check in Step 1
• Be concise but friendly — this is the user's first experience with Awareness